Ad
An ad consists of advertising materials. The set of parameters for an ad depends on its type.
Service
Restrictions
The ad type must match the group type. See the table in Ad type.
Operations with ads are not possible in archived campaigns.
To get the limit on the number of ads per group for an advertiser, use the method Clients.get or AgencyClients.get (see the ADS_TOTAL_PER_ADGROUP element in the Restrictions array).
For restrictions on ad parameters, see Quantitative restrictions in the Help for Yandex Direct.
- An ad in Ukrainian can only be added to a group that has the display region restricted to Ukraine.
- An ad in Belarusian can only be added to a group that has the display region restricted to Belarus.
- An ad in Kazakh can only be added to a group that has the display region restricted to Kazakhstan.
- An ad in Turkish can only be added to a group that has the display region restricted to Turkey.
Ad type
The ad type is set when creating an ad and can't be changed.
The following types of ads are currently available:
TEXT_AD — A text and image (normal) ad.
The ad contains a title and ad text, as well as a link to the advertised website. You can also include a Turbo page, display link, image, video extension, price, set of sitelinks, vCard, ad callouts, and the Yandex Maps business profile ID. If the Turbo page, vCard, or business profile ID is included, the website link is optional. The ad might be automatically assigned an age label. In this case, you can change the label.
To create or edit a text and image ad, pass its parameters in the TextAd structure of the add or update method.
To get the ad parameters (other than price parameters), list the parameter names in the TextAdFieldNames input parameter for the get method. To get the price parameters, list their names in the TextAdPriceExtensionFieldNames input parameter.
SMART_AD — Smart banner.
The ad contains a creative that was created in Ad Builder.
To create or edit an ad, pass the parameters in the SmartAdBuilderAd structure for the add or update method.
To get the ad parameters, list the parameter names in the SmartAdBuilderAdFieldNames input parameter of the get method.
MOBILE_APP_AD — An ad for advertising mobile apps.
The ad contains a title, text, and age restriction, as well as a label for the button to download or install. You can also add an image, specify a tracking link to track installs, and include a set of add-ons that need to be downloaded from the app store (icon, rating, and so on). For more information about advertising mobile apps, see Ads for Mobile Apps in the Help for Yandex Direct.
To create or edit an ad for mobile app advertising, pass its parameters in the MobileAppAd structure of the add or update method.
To get the parameters of a mobile ad, list the parameter names in the MobileAppAdFieldNames input parameter of the get method.
DYNAMIC_TEXT_AD — A dynamic ad.
The ad contains text. You can also include an image, a set of sitelinks, a vCard, and callouts with an ad. For more information about dynamic text ads, see Dynamic ads in the Help for Yandex Direct.
To create or edit a dynamic ad, pass its parameters in the DynamicTextAd structure of the add or update method.
To get the ad parameters, list the parameter names in the DynamicTextAdFieldNames input parameter for the get method.
IMAGE_AD — An image ad.
There are four subtypes of image ads:
TEXT_IMAGE_AD
The ad contains an image and a link to the advertised website and/or Turbo page.
To create or edit an ad, pass its parameters in the TextImageAd structure for the add or update method.
To get the ad parameters, list the parameter names in the TextImageAdFieldNames input parameter for the get method.
MOBILE_APP_IMAGE_AD
The ad contains an image. You can also add a tracking link to the ad for tracking installations.
To create or edit an ad, pass its parameters in the MobileAppImageAd structure for the add or update method.
To get the ad parameters, list the parameter names in the MobileAppImageAdFieldNames input parameter for the get method.
TEXT_AD_BUILDER_AD
The ad contains a creative that was designed in Ad Builder, as well as a link to the advertised website and/or Turbo page.
To create or edit an ad, pass its parameters in the TextImageAd structure for the add or update method.
To get the ad parameters, list the parameter names in the TextAdBuilderAdFieldNames input parameter for the get method.
MOBILE_APP_AD_BUILDER_AD
The ad contains a creative that was created in Ad Builder. You can also add a tracking link to the ad for tracking installations.
To create or edit an ad, pass its parameters in the MobileAppImageAd structure for the add or update method.
To get the ad parameters, list the parameter names in the MobileAppAdBuilderAdFieldNames input parameter for the get method.
Attention.Image ads are only displayed in ad networks (the Yandex Advertising Network and external networks); they are not displayed in search results.
Displays of image ads are possible only if the bid on a keyword or audience target meets the minimum CPC for an ad containing an image, which you can find on the Minimum and maximum CPC page.
For more information about image ads, see Image ads in the Help for Yandex Direct.
CPC_VIDEO_AD — A video ad (in a “Text & Image Ads” or “Ads for mobile apps” campaign).
The ad contains a creative that was designed in Ad Builder, as well as a link to the advertised website and/or Turbo page.
To create or edit an ad, pass its parameters in the CpcVideoAdBuilderAd structure for the add or update method.
To get the ad parameters, list the parameter names in the CpcVideoAdBuilderAdFieldNames input parameter of the get method.
The “Ads for mobile apps” campaigns use a separate subtype for video ads — MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD.- MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD
-
This kind of ad contains a creative that was created in Ad Builder. You can also add a tracking link to the ad for tracking installations.
To create or edit an ad, pass the parameters in the MobileAppCpcVideoAdBuilderAd structure for the add or update method.
To get the ad parameters, list the parameter names in the MobileAppCpcVideoAdBuilderAdFieldNames input parameter of the get method.
CPM_BANNER_AD — A display banner.
The ad contains a creative that was uploaded in the web interface or designed in Ad Builder, as well as a link to the advertised website and/or Turbo page. You can also add a Yandex Audience pixel and an ADFOX impression tag to ads.
To create or edit an ad, pass the parameters in the CpmBannerAdBuilderAd structure for the add or update method.
To get the ad parameters, list the parameter names in the CpmBannerAdBuilderAdFieldNames input parameter of the get method.
CPM_VIDEO_AD — A video display ad (in a “Display campaign”).
The ad contains a creative that was designed in Ad Builder, as well as a link to the advertised website and/or Turbo page. You can also add an ADFOX impression tag to an ad.
To create or edit an ad, pass the parameters in the CpmBannerAdBuilderAd structure for the add or update method.
To get the ad parameters, list the parameter names in the CpmBannerAdBuilderAdFieldNames input parameter of the get method.
The Type, Subtype, Status, State, StatusClarification, AdCategories, and AgeLabel parameters are common to all types of ads. To get these parameters, list the desired parameter names in the FieldNames input parameter of the get method.
The table below shows how ad types correspond to group types.
| Ad group type | Possible types of ads |
|---|---|
| TEXT_AD_GROUP | TEXT_AD IMAGE_AD with subtypes TEXT_IMAGE_AD and TEXT_AD_BUILDER_AD CPC_VIDEO_AD |
| SMART_AD_GROUP | SMART_AD |
| MOBILE_APP_AD_GROUP | MOBILE_APP_AD IMAGE_AD with subtypes MOBILE_APP_IMAGE_AD and MOBILE_APP_AD_BUILDER_AD CPC_VIDEO_AD, the subtype MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD |
| DYNAMIC_TEXT_AD_GROUP | DYNAMIC_TEXT_AD |
| CPM_BANNER_AD_GROUP | CPM_BANNER_AD |
| CPM_VIDEO_AD_GROUP | CPM_VIDEO_AD |
| Ad group type | Possible types of ads |
|---|---|
| TEXT_AD_GROUP | TEXT_AD IMAGE_AD with subtypes TEXT_IMAGE_AD and TEXT_AD_BUILDER_AD CPC_VIDEO_AD |
| SMART_AD_GROUP | SMART_AD |
| MOBILE_APP_AD_GROUP | MOBILE_APP_AD IMAGE_AD with subtypes MOBILE_APP_IMAGE_AD and MOBILE_APP_AD_BUILDER_AD CPC_VIDEO_AD, the subtype MOBILE_APP_CPC_VIDEO_AD_BUILDER_AD |
| DYNAMIC_TEXT_AD_GROUP | DYNAMIC_TEXT_AD |
| CPM_BANNER_AD_GROUP | CPM_BANNER_AD |
| CPM_VIDEO_AD_GROUP | CPM_VIDEO_AD |
Ad status and state
The State parameter reflects the current state of the ad.
| State | Description |
|---|---|
| SUSPENDED | Ad displays were stopped by the owner using the suspend method or in the web interface. |
| OFF_BY_MONITORING | Ad displays are automatically stopped by site availability monitoring. |
| ON | The ad is active, belongs to an active campaign, and can be served (if the campaign has funds, time targeting settings allow impressions, and so on). |
| OFF | The ad is inactive (a draft, pending review, or rejected), or belongs to an inactive or suspended campaign. |
| ARCHIVED | The ad has been archived (using the archive method, or in the web interface), or belongs to an archived campaign. |
| State | Description |
|---|---|
| SUSPENDED | Ad displays were stopped by the owner using the suspend method or in the web interface. |
| OFF_BY_MONITORING | Ad displays are automatically stopped by site availability monitoring. |
| ON | The ad is active, belongs to an active campaign, and can be served (if the campaign has funds, time targeting settings allow impressions, and so on). |
| OFF | The ad is inactive (a draft, pending review, or rejected), or belongs to an inactive or suspended campaign. |
| ARCHIVED | The ad has been archived (using the archive method, or in the web interface), or belongs to an archived campaign. |
The Status parameter reflects the result of reviewing the ad.
| Status | Description |
|---|---|
| DRAFT | The ad has been created but has not yet been submitted for review. |
| MODERATION | The ad is under review. |
| PREACCEPTED | The ad has been automatically accepted for displays, but will be further reviewed by a moderator. |
| ACCEPTED | The ad was accepted after review. |
| REJECTED | The ad was rejected after review. |
| Status | Description |
|---|---|
| DRAFT | The ad has been created but has not yet been submitted for review. |
| MODERATION | The ad is under review. |
| PREACCEPTED | The ad has been automatically accepted for displays, but will be further reviewed by a moderator. |
| ACCEPTED | The ad was accepted after review. |
| REJECTED | The ad was rejected after review. |
If the ad was edited, and the new version is pending review (the MODERATION status) or was immediately rejected after review (the REJECTED status), the previous version of the ad continues being served if it was not suspended. In this case, the ad has the ON status.
If the new version of the ad was automatically accepted for display after editing (PREACCEPTED), and then it was rejected (REJECTED), displays of the previous version will not be resumed.
Special category
During the review, an ad can be assigned a label stating that the advertised product or service belongs to a special category. In this case, the ad is given the AdCategories parameter, which cannot be changed.
For certain categories, ad displays are forbidden. For others, ads are served with a special warning in accordance with the legislation of the Russian Federation.
To get the reference list of special categories, use the Dictionaries.get method.
These categories cannot be changed, assigned, or removed via the API. If you disagree with the category assigned, contact the Support service.
Age label
The AgeLabel parameter contains the age-appropriate category of the advertised product, if this category is required to be specified by the federal law of the Russian Federation “About advertising”. The way the age category is assigned depends on the type of ad.