Ad Site Setting¶

Abstract¶

Ad Site Setting is a new RESTful object, available in the v3 Yahoo Native API, that provides methods for creating, updating, and retrieving settings for site-specific ads, including pagination. A site-specific ad is a native ad that has been tagged by the advertiser to be shown to a user when that user visits a specific website.

Overview¶

Ad Site Setting entities are created on the ad level, using the Ad Site Setting endpoint. Support is provided for the following campaign objectives in the API:

VISIT_WEB
PROMOTE_BRAND
INSTALL_APP

Support is also provided for single image, video and carousel ad types.

Example Use Case¶

Take the use case, for example, of an automobile dealer whose account includes advertising for different autos. If a potential customer visits the Yahoo Homepage, an ad of a sedan can be tagged in an ad group that may be shown directly to that customer. Another ad of a sport utility vehicle in that same ad group can also be tagged that may be shown to a customer who visits the Yahoo Finance page.

In this case, the site-specific ad may be shown under the following conditions:

If the site-specific ad is performing better than the regular ad or ads in the ad group. Yahoo Native will automatically determine if this is the case and display the better-performing, site-specific ad.
If the site-specific ad is not performing better than the regular ad or ads, Yahoo Native will not use the site-specific ad for the sites for which it was tagged, but rather, the regular ads.
Yahoo Native will never show a site-specific ad on a site other than the ones for which it was tagged.

Important

Performance metrics for site-specific ads will appear in the same reporting views next to those of regular ads. Advertisers can then easily compare the two different ads based on ad ids or ad names in the reporting view, and determine precisely the one that is indeed performing better.

Endpoint¶

Resource URI

https://api.gemini.yahoo.com/v3/rest/adsitesetting/

Fields¶

Ad Site Setting includes the following fields:

Name	Description	Type	Add	Update
`adId`	The ID of the ad to be tagged or untagged with a specific site.	long	required	optional
`advertiserId`	The ID of the advertiser to which the ad with the site setting belongs.	long	required	optional
`status`	The status of the object. Valid values: `ACTIVE` `DELETED`	enum	required	optional
`value`	The site name. Use this for create operations. Refer to Site X Device Targeting for a comprehensive list of site names to target.	enum	required	optional

Example Representation¶

Ad Site Setting

{
 "value": "HOMEPAGE_US",
 "id": 338497,
 "status": "ACTIVE",
 "advertiserId": 87292,
 "adId": 46756
}

Ad Site Setting Response

{
  "errors": null,
  "response": [
     {
         "value": "HOMEPAGE_US",
         "id": 1234,
         "status": "ACTIVE",
         "advertiserId": 87292,
         "adId": 46756
        }
  ]
}

Operations¶

Read

Method: To retrieve data for an ad site setting, make a GET call with the ID parameter:

GET https://api.gemini.yahoo.com/v3/rest/adsitesetting/1234

The response will be the ad site setting associated with the id:

{
  "errors": null,
  "response": [
    {
         "value": "HOMEPAGE_US",
         "id": 1234,
         "status": "ACTIVE",
         "advertiserId": 87292,
         "adId": 46756
        }
  ]
}

Method: To retrieve data for an ad site setting with multiple IDs, make a GET call with the ID parameter:

GET https://api.gemini.yahoo.com/v3/rest/adsitesetting?id=1234&id=5678

    The response will be the ad site settings associated with multiple ids:

    {
      "errors": null,
      "response": [
         {
                     "value": "HOMEPAGE_US",
                     "id": 1234,
                     "status": "ACTIVE",
                     "advertiserId": 87292,
         },
         {
                     "value": "HOMEPAGE_US",,
                     "id": 5678,
                     "status": "ACTIVE",
                     "advertiserId": 87292,
                     "adId": 46756
         }
      ]
    }

Read data for a filtered list of ad site settings

Method: To retrieve data for a filtered list of ad site settings, make a GET call with the following parameters:

Name	Description	Type
`mr`	The maximum number of rows to retrieve.	int
`si`	The start index or the first element to retrieve.	int
`adId`	The ID of the ad. This is required.	long
`advertiserId`	The ID of the advertiser to filter the site specific settings by. This is required.	long
`value`	The site name to filter by.	string
`status`	The site specific status to filter by.	string

Important

Only one advertiserId parameter is allowed to be passed in as a query parameter for all filtered lists of ad site settings calls.

Create a new ad site setting

Method: To create a new ad site setting, make a POST call. The response will be the newly created ad site setting.

For example:

POST https://api.gemini.yahoo.com/v3/rest/adsitesetting/

{
 "value": "HOMEPAGE_US",
 "status": "ACTIVE",
 "advertiserId": 87292,
 "adId": 46756
}

Update existing ad site setting

Method: To update existing ad site setting, make a PUT call. The result will be the list of updated ad site settings.

PUT  https://api.gemini.yahoo.com/v3/rest/adsitesetting/

{
 "id": 338497,
 "status": "ACTIVE"
}

Delete an ad site setting

Method: To delete an ad site setting, make a PUT call.

For example:

DELETE  https://api.gemini.yahoo.com/v3/rest/adsitesetting/1234
DELETE  https://api.gemini.yahoo.com/v3/rest/adsitesetting?id=1234&id=5678

PUT https://api.gemini.yahoo.com/v3/rest/adsitesetting/

{
  "status": "DELETED",
  "id": 103002
}

Best Practices & Issues¶

The following are some best practices and issues you need to understand when working with site-specific ads.

Important

To ensure that site-specific ads only serve on the sites to which they are tagged, please set the tags to the ad BEFORE turning the status of the ad to ON. Otherwise, the ad will serve everywhere if it is marked as ON – up until the tags are set to the ad. Even after the tags are set, there will be some latent clicks and impressions trickling in for a few hours for ad serves that occurred before the tags were set. The key point is that you should set the site tags on the ad before you take the ad live, so that it does not end up getting served on other supply options at all.

If you create a site-specific ad in an ad group that doesn’t have regular, active ad attached to them, the site-specific ad will fail to be created. You must first create regular ads (i.e., one without site-specific settings), and then create a separate site-specific ad.
If the only regular ad in an ad group is deleted or paused and one or more site-specific ads are present in that same ad group, Yahoo Native will automatically pick one of the site-specific ads randomly, remove the site-specific settings and make it a regular ad.
If the only regular ad in an ad group is rejected and one or more site-specific ads are present in that same ad group, Yahoo Native will automatically pick one of the site-specific ads randomly, remove the site-specific settings and make it a regular ad.
If the only regular ad in an ad group is changed to a site-specific ad and one or more site-specific ads are present in that same ad group, Verizon Media Ad Platform will return an error. You will need to create another regular ad or convert a site-specific ad to a regular ad.
If a site-specific ad is converted back to a regular ad by removing the site-specific settings, Verizon Media Ad Platform will treat it as a regular ad.
If a site-specific ad is paused, deleted or rejected, Verizon Media Ad Platform will continue to serve the other ads (regular or site-specific ads) in that ad group.
If more than one site-specific ad within the same ad group is set to the same site, Yahoo Native will serve either of the two site-specific ads or any other regular ad in that ad group on that site, to the extent that one of those ads is performing better than the others.
If the regular ad is paused or deleted when there is one or more site-specific ads present in that ad group, and subsequently that regular ad is turned back on, there will be no change to the remaining site-specific ads when the original regular ad is turned back on. This is because one of the site-specific ads would already have been changed to a regular ad by Yahoo Native when the ad was paused or deleted, as detailed in item #2 listed above.
If the regular ad performs better than the site-specific ad, the regular ad will override the site-specific ad when it is served.
If you have ads pointing to desktop site, it won’t serve on those sites. Mobile targeting will supersede desktop settings.
You may choose to have more than one regular ad. As always, the ad that performs best will be served.