An ad consists of advertising materials. The set of parameters for an ad depends on its type.
Use the Ads service for managing ads.
Maximum of 50 ads per ad group.
The ad type must match the group type. See the table in Ad type.
For restrictions on ad parameters, see Quantitative restrictions in the Help for Yandex.Direct.
Operations with ads are not possible in archived campaigns.
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 display link, an image, a video extension, a set of sitelinks, a vCard, and callouts with an ad. If there is a vCard, the website link is optional. An ad can be automatically assigned an age label. In this case, you can change the label.
To get the ad parameters, list the parameter names in the TextAdFieldNames input parameter for 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 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.
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:
The ad contains an image and a link to the advertised website.
To get the ad parameters, list the parameter names in the TextImageAdFieldNames input parameter for the get method.
The ad contains an image. You can also add a tracking link to the ad for tracking installations.
To get the ad parameters, list the parameter names in the MobileAppImageAdFieldNames input parameter for the get method.
The ad contains a creative that was created in the Ad Builder and a link to the advertised website.
To get the ad parameters, list the parameter names in the TextAdBuilderAdFieldNames input parameter for the get method.
The ad contains a creative that was created in the Ad Builder. You can also add a tracking link to the ad for tracking installations.
To get the ad parameters, list the parameter names in the MobileAppAdBuilderAdFieldNames input parameter for the get method.
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.
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 for the get method.
The table below shows how ad types correspond to group types.
|Group type||Possible types of ads|
IMAGE_AD with subtypes TEXT_IMAGE_AD and TEXT_AD_BUILDER_AD
IMAGE_AD with subtypes MOBILE_APP_IMAGE_AD and MOBILE_APP_AD_BUILDER_AD
The State parameter reflects the current state of the ad.
|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 displayed (if the campaign has funds, time targeting settings allow displays, 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.
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 displayed 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.
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 displayed with a special warning in accordance with the legislation of the Russian Federation.
These categories cannot be changed, assigned, or removed via the API. If you disagree with the category assigned, contact the Support service.
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.
The value of the age label depends on whether the ad belongs to the special category BABY_FOOD:
For ads that belong to the BABY_FOOD category, it is the age of the infant in months: "MONTHS_0", "MONTHS_1", "MONTHS_2", ..., "MONTHS_12".
For all other ads, it is the age that the informational product is appropriate for. Possible values: "AGE_0", "AGE_6", "AGE_12", "AGE_16", "AGE_18".
If an ad does not have an age label, this parameter can't be set (the update method ignores the parameter value).
The API can only be used to change the value of the age category, if the ad has one. In order to change whether an ad has or doesn't have an age category, contact the Support service.
An age label is assigned to all ads. Possible values: "AGE_0", "AGE_6", "AGE_12", "AGE_16", "AGE_18".
The label can be specified when creating the ad. The default value is "AGE_18". You can change the value of the label when editing the ad, but you can't remove the label.
You can use the add and update methods to link a vCard, image, video extension, set of sitelinks, or callouts with an ad (depending on the ad type). To learn how to do this, see Adding vCards, images, sitelinks, callouts, and video extensions to an ad.
Images and video extensions are only displayed in ad networks (the Yandex Advertising Network and external networks); they are not displayed in search results.
An image or video extension can be displayed only if the bid for the 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. Otherwise, the ad is shown without the image or video extension.
The vCard, image, video extension, and sitelinks are not reviewed in isolation, but together with the ad. They are submitted for review automatically if the ad itself is under review or has already been reviewed.
The get method returns the result of reviewing the vCard (VCardModeration structure), image (AdImageModeration structure), sitelinks (SitelinksModeration structure), or video extension (Status parameter in the VideoExtension structure).
|DRAFT||The add-on has not been submitted for review.|
The add-on is under review.
|ACCEPTED||The add-on was accepted after review. The ad will contain the add-on when it is shown.|
|REJECTED||The add-on was rejected after review.|
|UNKNOWN||The status is unknown. This value is used for backward compatibility and for displaying statuses that are not supported in this version of the API.|