Welcome to the Yahoo Gemini API Product Bulletin. This update includes a quick snapshot of recent and upcoming releases and is focused on features supported by the API. A summary of supported functionality is also included.
Product Bulletins are updated on a monthly cadence for Gemini API partners, account managers and developers.
- September, 2017
- Re-engagement for Mobile App Installs
- Yahoo Gemini Native Bid Adjustments Update
- Bulk Downloads Performance Reminder
- Reminder: New Reporting Cubes and Resources: Gemini V3 API and Upgraded URLs (UUs)
- Reminder: Migration to Gemini v2 API or v3 API - Action May Be Required
- Reminder: v1 API Deprecation
- Reminder: Deprecated v1 Reporting Endpoint
- Gemini Native Ads Specs and Resources
- Gemini API Video Tutorials
- Getting Started Guide: OAuth 2.0 Authentication Steps
- Glossary of Gemini Terms
- Check Out What’s New
- Using the Gemini Sandbox Environment
- Required Fields by Ad Type Matrix
Re-engagement for Mobile App Installs¶
Use the new campaign objective Re-Engage my app to drive users to relaunch your mobile app and optimize to in-app events. Key benefits:
- Increase user retention and return with in-app, post-installation events.
- Tap into Yahoo supply via Native display.
- Increase your mobile app marketing revenue by unlocking a new type of demand and lift in mobile eCPM.
- Leverage existing App Install campaign installation conversion data.
For details, see the API and BULK documentation in the Gemini Guide:
- Campaigns - See REENGAGE_APP campaign objective
- Adgroup - Supported Price Type is CPC
- Ad and Matrix view of required ad fields
- BULK Field Objects - See ReengageApp
- BULK Device Targeting - Device targeting (Desktop, Smartphone, Tablet) applies primarily to Gemini Search campaigns. However, for Native campaigns, this does apply to InstallApp and ReengageApp campaigns. Device targeting can be set at either the campaign or ad group level.
- BULK OS Version Targeting- OS Version target is available for InstallApp and ReengageApp native campaigns and can be set at the ad group level.
For additional reference, see the Advertiser Guide: Drive Mobile Re-Engage App Campaigns. Also see How to Drive Mobile App Installs for background on App Install campaigns, including a step-by-step video of campaign setup in the UI.
Yahoo Gemini Native Bid Adjustments Update¶
Beginning on Monday, 9/18/17, Gemini will be shifting high-performing publisher sites from group “3b” to group “2b”. Advertisers should review “2b” modifiers to ensure they are in place prior to Monday as there may be increased traffic flowing through this group. For API documentation on the SUPPLY_GROUP attribute, see Bid Modifiers.
Native Bid Adjustments, introduced in October 2016, is a feature extension to the Yahoo Gemini Native family that provides advertisers with greater control over their campaign performance. Native advertisers can adjust bids by both supply and device. Using Native Bid Adjustments, you can modify positive and negative bid thresholds, enabling you to better control supply, as well as influence platform performance.
- For API documentation, see Targeting Attribute > Bid Modifiers
- For information on Bulk Field Objects, see Supply Targeting
- Also reference the Gemini Advertiser Guide for details on how it works: https://developer.yahoo.com/gemini/advertiser/guide/targeting/native-bid-adjustments/
Bulk Downloads Performance Reminder¶
If you have a large account and notice your bulk downloads are taking longer over time, please consider deleting dormant or orphaned objects (i.e., Campaigns, Keywords, Ads, Ad Groups). See the Gemini Guide for more details on Bulk operations.
Reminder: New Reporting Cubes and Resources: Gemini V3 API and Upgraded URLs (UUs)¶
The new Gemini v3 API has been released as of July 25, 2017. We’ve introduced new Reporting cubes this month, for querying at the ad group level. For more information, refer to Cubes.
site_performance_statswhen querying for native ads campaign data.
campaign_bid_performance_statswhen evaluating group-level bid modifiers.
- New reporting dimensions available for querying at the advertiser, ad, campaign, ad group and keyword levels. For more information, refer to Dimensions.
- Postman examples added for Upgraded URLs (v3) and Bid by Site (v2). For more information, refer to Postman API Toolkit.
In addition to the above new resources, the Gemini v3 API release provides partners and developers with following advantages:
- Support for Upgraded URLs (UUs), which enable you to better define and control the landing page and tracking of your URLs. For more information on Upgraded URLs (UUs) in the new Gemini v3 API, refer to Upgraded URLs. Note the Migration Path and Upgrade Account to Work as UU sections.
- Greater API object stability, as well as improved management of API changes, building on the enhancements in the Gemini v2 API.
- Support for Site X Device Targeting with new available targeting attributes. For more information about Site X Device Targeting, refer to v3 Site X Device Targeting.
- Additional bug and error fixes for improved performance and stability.
- See the What’s New section and Navigating the API for more information about the new Gemini v3 API. Developers are encouraged to migrate to the v3 Gemini API in order to maintain access to the latest features and functionality. Please note that new features are only added to the current version. For reference, see details on v2 Objects.
Reminder: Migration to Gemini v2 API or v3 API - Action May Be Required¶
Please be aware that starting on September 1, 2017, the Gemini v1 API was relegated to End of Life (EOL) status; the Gemini v3 API was released on July 25, 2017. The Gemini v2 API is still supported post-release. Official deprecation for the v2 API has not yet occurred. Partners and developers will be notified once this has been officially determined, and a schedule provided. Please note that new features will not be added to v1, and v1 will not be supported. For details on the v3 release schedule, as well as dates for the v1 deprecation, see the Release Schedule and Gemini API Versioning.
Action may be required: Gemini API users may choose to migrate to either v2 API or v3 API.
To migrate to v2 API:
- Please visit the v1 deprecation note.
- Note: Action may be required to migrate from the Deprecated v1 Reporting Endpoint.
To migrate to v3 API:
- Users are encouraged to migrate to the new Gemini v3 API directly. v3 is backward compatible with v2, and users may continue using the current landing/display URL structure on v3 without Upgraded URLs migration for the time being. The new Gemini v3 API has been released as of July 25, 2017. This release provides partners and developers with multiple new features and capabilities. For details, see Versioning.
Reminder: v1 API Deprecation¶
- Reminder: The Gemini v1 API was deprecated on June 1, 2016. Starting on September 1, 2017, the Gemini v1 API will be relegated to End of Life (EOL) status. In addition, new features will not be added to v1.
Reminder: Deprecated v1 Reporting Endpoint¶
- Please be aware that action may be required for the following deprecated reporting endpoint.
Old: https://api.gemini.yahoo.com/v1/rest/reports New: https://api.gemini.yahoo.com/v2/rest/reports/custom
- If you currently make calls only to /v2/rest/reports/custom for both POST and GET, there is no action required.
- If you currently make POST calls to /v1/rest/reports then you need to migrate to the /v2/rest/reports/custom endpoint ASAP.
- If you currently make POST calls to /v1/rest/reports/custom and GET calls to /v1/rest/reports, then you need to migrate to v2 before v1 EOL THIS year Sept 1, 2017.
Gemini Native Ads Specs and Resources¶
- Native ads combine various brand assets to produce rich, compelling ad experiences and display them alongside content, providing interaction and engagement superior to traditional display advertising. See Gemini Native Ads for details on native ads, including key benefits, where native ads appear, and detailed information about various Yahoo Gemini native ad types.
Gemini API Video Tutorials¶
- In this series of introductory videos, the Gemini Development Team will walk you through some of the basic steps you’ll need to follow before you first begin making API calls and leveraging the Gemini platform for programmatic ad buying.
- Get Started with Programmatic Gemini API - Episode 1
- Working with RESTful Objects in Programmatic Gemini API - Episode 2
- How to set up your Sandbox Environment in the Programmatic Gemini API - Episode 3
Getting Started Guide: OAuth 2.0 Authentication Steps¶
- New, detailed explanation of steps to follow before you begin OAuth 2.0 authentication. If you’re new to the Gemini API, you should read the section and follow the steps listed. Note also in the section on OAuth refresh tokens that access tokens will expire after 60 minutes.
Glossary of Gemini Terms¶
Check Out What’s New¶
Using the Gemini Sandbox Environment¶
- The Gemini API lets you work with a sandbox environment to test campaigns you’ve created and managed. You use the same consumer key and consumer secret you obtained when you set up your OAuth to access the sandbox.
- The Gemini sandbox serves as a modified version of the production environment. While all operations are designed to function the same in the sandbox as in the production environment, the campaigns and ads you create in this environment do not actually serve. The sandbox environment is completely separate from your production environment.
- All campaigns, ads, and keywords you create in the sandbox are available in the sandbox environment only. There is no possibility that the ads you create in the sandbox will be accidentally served. Nor will your production accounts be charged for any mock transactions in the sandbox environment.
- You will need to create a sandbox account in order to test in this environment. You can do this by making a POST call to the sandbox signup endpoint and passing in the name you wish to call your test advertiser. The response will be a test advertiser object that will only be available in the sandbox environment. For more details, see Testing - Sandbox.
- Be sure to check out the video tutorial describing How to set up your Sandbox Environment in the Programmatic Gemini API - Episode 3.
Required Fields by Ad Type Matrix¶
- We’ve added a new matrix which details the required fields when serving different ad types. For more information, see Ad documentation > Matrix view of required fields.