add
Создает группы объявлений.
Ограничения
Для работы с Единой перфоманс-группой используется адрес https://api.direct.yandex.com/v501/
.
Не допускается добавление группы в архивную кампанию.
Не более 1000 групп в одном вызове метода.
Ограничение на количество групп объявлений в кампании для рекламодателя можно получить с помощью метода Clients.get или AgencyClients.get (элемент ADGROUPS_TOTAL_PER_CAMPAIGN массива Restrictions).
Запрос
Структура запроса в формате JSON:
{
"method": "add",
"params": { /* params */
"AdGroups": [{ /* AdGroupAddItem */
"Name": (string), /* required */
"CampaignId": (long), /* required */
"RegionIds": [(long), ... ], /* required */
"NegativeKeywords": { /* ArrayOfString */
"Items": [(string), ... ] /* required */
},
"NegativeKeywordSharedSetIds": { /* ArrayOfLong */
"Items": [(long), ... ] /* required */
},
"TrackingParams": (string),
"MobileAppAdGroup": { /* MobileAppAdGroupAdd */
"StoreUrl": (string), /* required */
"TargetDeviceType": [( "DEVICE_TYPE_MOBILE" | "DEVICE_TYPE_TABLET" ), ... ], /* required */
"TargetCarrier": ( "WI_FI_ONLY" | "WI_FI_AND_CELLULAR" ), /* required */
"TargetOperatingSystemVersion": (string) /* required */
},
"DynamicTextAdGroup": [{ /* DynamicTextAdGroupAdd */
"DomainUrl": (string) /* required */,
"AutotargetingCategories" : [{ /* AutotargetingCategoriesAdd */
"Category" : ( "EXACT" | "ALTERNATIVE" | "COMPETITOR" | "BROADER" | "ACCESSORY" ) /* required */,
"Value" : ( "YES" | "NO" ) /* required */
}, ...]
}, ...],
"DynamicTextFeedAdGroup": [{ /* DynamicTextFeedAdGroupAdd */
"FeedId": (long) /* required */,
"AutotargetingCategories" : [{ /* AutotargetingCategoriesAdd */
"Category" : ( "EXACT" | "ALTERNATIVE" | "COMPETITOR" | "BROADER" | "ACCESSORY" ) /* required */,
"Value" : ( "YES" | "NO" ) /* required */
}, ...]
}, ...],
"CpmBannerKeywordsAdGroup": { /* CpmBannerKeywordsAdGroupAdd */
},
"CpmBannerUserProfileAdGroup": { /* CpmBannerUserProfileAdGroupAdd */
},
"CpmVideoAdGroup": { /* CpmVideoAdGroupAdd */
},
"SmartAdGroup": { /* SmartAdGroupAdd */
"FeedId": (long), /* required */
"AdTitleSource": (string),
"AdBodySource": (string)
},
"UnifiedAdGroup" : {
"OfferRetargeting" : ("YES"|"NO") /* required */
},
"TextAdGroupFeedParams" : { /*TextAdGroupFeedParamsAdd */
"FeedId" : (long) /* required */,
"FeedCategoryIds" : {
"Items" : [ (long) ] /* required */
}
}
}, ... ] /* required */
}
}
Параметр | Тип | Описание | Обяза- тельный |
Структура params (для JSON) / AddRequest (для SOAP) | |||
---|---|---|---|
AdGroups | array of AdGroupAddItem | Группы, которые требуется добавить. | Да |
Структура AdGroupAddItem | |||
Name | string | Название группы объявлений (от 1 до 255 символов). | Да |
CampaignId | long | Идентификатор кампании, в которую добавляется группа. | Да |
RegionIds | array of long | Массив идентификаторов регионов, для которых показы включены или выключены. Массив должен содержать хотя бы один элемент. Идентификатор 0 — показывать во всех регионах. Минус перед идентификатором региона — выключить показы в данном регионе. Например [1,-219] — показывать для Москвы и Московской области, кроме Черноголовки. Минус-регионы нельзя использовать, если указан 0. Массив не должен состоять только из минус-регионов. Справочник регионов можно получить с помощью метода Dictionaries.get. | Да |
NegativeKeywords | ArrayOfString | Массив минус-фраз, общих для всех ключевых фраз группы объявлений. Ограничение. Минус-фразы не допускаются в группе медийных объявлений с условием нацеливания по профилю пользователей. Минус-фразу следует указывать без минуса перед первым словом. Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Пробелы, дефисы и операторы не учитываются в суммарной длине. Примечание. Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании. | Нет |
NegativeKeywordSharedSetIds | ArrayOfLong | Идентификаторы наборов минус-фраз. Не более 3 элементов в массиве. Получить идентификаторы наборов можно с помощью метода NegativeKeywordSharedSets.get. Ограничение. Минус-фразы не допускаются в группе медийных объявлений с условием нацеливания по профилю пользователей. | Нет |
TrackingParams | string | GET-параметры для отслеживания источников переходов на сайт, которые добавляются в ссылку всех объявлений группы (не более 1024 символов). Могут содержать подстановочные переменные. Например: from=direct&ad={ad_id} Параметр можно указать для групп текстово-графических объявлений, динамических объявлений и смарт-баннеров, но в настоящее время он используется только для групп динамических объявлений и смарт-баннеров. | Нет |
MobileAppAdGroup | MobileAppAdGroupAdd | Параметры группы объявлений для рекламы мобильных приложений. | Нет |
DynamicTextAdGroup | DynamicTextAdGroupAdd | Параметры группы динамических объявлений. | Нет |
DynamicTextFeedAdGroup | DynamicTextFeedAdGroupAdd | Параметры группы динамических объявлений с подтипом FEED. | Нет |
CpmBannerKeywordsAdGroup | CpmBannerKeywordsAdGroupAdd | Параметры группы медийных объявлений с ключевыми фразами. Чтобы создать такую группу, укажите пустую структуру CpmBannerKeywordsAdGroup. | Нет |
CpmBannerUserProfileAdGroup | CpmBannerUserProfileAdGroupAdd | Параметры группы медийных объявлений с условием нацеливания по профилю пользователей. Чтобы создать такую группу, укажите пустую структуру CpmBannerUserProfileAdGroup. | Нет |
CpmVideoAdGroup | CpmVideoAdGroupAdd | Параметры группы медийных видеообъявлений (в кампании с типом «Медийная кампания»). Чтобы создать такую группу, укажите пустую структуру CpmVideoAdGroup. | Нет |
SmartAdGroup | SmartAdGroupAdd | Параметры группы смарт-баннеров. | Нет |
UnifiedAdGroup | UnifiedAdGroupAdd | Параметры единой перфоманс группы. См. Тип группы. | Нет |
TextAdGroupFeedParams | TextAdGroupFeedParams | Параметры фида и идентификаторы категорий для группы текстово-графических объявлений. | Нет |
Структура MobileAppAdGroupAdd | |||
StoreUrl | string | Ссылка на приложение в магазине приложений AppStore или Google Play (не более 1024 символов). Должна содержать протокол. Недоступна для изменения. См. раздел Ссылка на приложение в магазине приложений помощи Директа. Ограничение. Во всех группах объявлений одной кампании должна быть указана одинаковая ссылка на приложение. Если в кампании ранее были созданы группы с разными ссылками на приложение, то при добавлении разрешено указать ссылку на приложение, которое отображается в параметрах кампании в веб-интерфейсе Директа. | Да |
TargetDeviceType | array of DeviceTypeEnum | На каких устройствах показывать объявления:
| Да |
TargetCarrier | CarrierEnum | По каким типам подключения к интернету показывать объявления:
| Да |
TargetOperatingSystemVersion | string | Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3. Примечание. Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше. | Да |
Структура DynamicTextAdGroupAdd | |||
DomainUrl | string | Доменное имя сайта, для которого требуется сгенерировать динамические объявления (не более 100 символов). Протокол указывать не нужно. | Да |
AutotargetingCategories | array of AutotargetingCategoriesAddItem | Категории таргетинга, которые требуется добавить. | Нет |
Структура DynamicTextFeedAdGroupAdd | |||
FeedId | long | Идентификатор фида, на основе которого требуется сгенерировать динамические объявления. | Да |
AutotargetingCategories | array of AutotargetingCategoriesAddItem | Категории таргетинга, которые требуется добавить. | Нет |
Структура AutotargetingCategoriesAddItem | |||
Category | AutotargetingCategoriesEnum | Категория таргетинга:
| Да |
Value | YesNoEnum | Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. | Да |
Структура SmartAdGroupAdd | |||
FeedId | long | Идентификатор фида, на основе которого требуется сгенерировать смарт-баннеры. | Да |
AdTitleSource | string | Название элемента фида, из которого нужно брать заголовок объявления. Если не задано, заголовок генерируется автоматически. | Нет |
AdBodySource | string | Название элемента фида, из которого нужно брать текст объявления. Если не задано, текст генерируется автоматически. | Нет |
Структура UnifiedAdGroupAdd | |||
OfferRetargeting | YesNoEnum | Признак включения офферного ретаргетинга. | Да |
Структура TextAdGroupFeedParamsAdd | |||
FeedId | long | Идентификатор фида, на основе которого требуется сгенерировать текстово-графические объявления. | Да |
FeedCategoryIds | ArrayOfLong | Идентификаторы категорий товаров, на основе которых требуется сгенерировать текстово-графические объявления. Если идентификаторы категорий не заданы, используются все категории из фида. | Нет |
Параметр | Тип | Описание | Обяза- тельный |
Структура params (для JSON) / AddRequest (для SOAP) | |||
---|---|---|---|
AdGroups | array of AdGroupAddItem | Группы, которые требуется добавить. | Да |
Структура AdGroupAddItem | |||
Name | string | Название группы объявлений (от 1 до 255 символов). | Да |
CampaignId | long | Идентификатор кампании, в которую добавляется группа. | Да |
RegionIds | array of long | Массив идентификаторов регионов, для которых показы включены или выключены. Массив должен содержать хотя бы один элемент. Идентификатор 0 — показывать во всех регионах. Минус перед идентификатором региона — выключить показы в данном регионе. Например [1,-219] — показывать для Москвы и Московской области, кроме Черноголовки. Минус-регионы нельзя использовать, если указан 0. Массив не должен состоять только из минус-регионов. Справочник регионов можно получить с помощью метода Dictionaries.get. | Да |
NegativeKeywords | ArrayOfString | Массив минус-фраз, общих для всех ключевых фраз группы объявлений. Ограничение. Минус-фразы не допускаются в группе медийных объявлений с условием нацеливания по профилю пользователей. Минус-фразу следует указывать без минуса перед первым словом. Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Пробелы, дефисы и операторы не учитываются в суммарной длине. Примечание. Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании. | Нет |
NegativeKeywordSharedSetIds | ArrayOfLong | Идентификаторы наборов минус-фраз. Не более 3 элементов в массиве. Получить идентификаторы наборов можно с помощью метода NegativeKeywordSharedSets.get. Ограничение. Минус-фразы не допускаются в группе медийных объявлений с условием нацеливания по профилю пользователей. | Нет |
TrackingParams | string | GET-параметры для отслеживания источников переходов на сайт, которые добавляются в ссылку всех объявлений группы (не более 1024 символов). Могут содержать подстановочные переменные. Например: from=direct&ad={ad_id} Параметр можно указать для групп текстово-графических объявлений, динамических объявлений и смарт-баннеров, но в настоящее время он используется только для групп динамических объявлений и смарт-баннеров. | Нет |
MobileAppAdGroup | MobileAppAdGroupAdd | Параметры группы объявлений для рекламы мобильных приложений. | Нет |
DynamicTextAdGroup | DynamicTextAdGroupAdd | Параметры группы динамических объявлений. | Нет |
DynamicTextFeedAdGroup | DynamicTextFeedAdGroupAdd | Параметры группы динамических объявлений с подтипом FEED. | Нет |
CpmBannerKeywordsAdGroup | CpmBannerKeywordsAdGroupAdd | Параметры группы медийных объявлений с ключевыми фразами. Чтобы создать такую группу, укажите пустую структуру CpmBannerKeywordsAdGroup. | Нет |
CpmBannerUserProfileAdGroup | CpmBannerUserProfileAdGroupAdd | Параметры группы медийных объявлений с условием нацеливания по профилю пользователей. Чтобы создать такую группу, укажите пустую структуру CpmBannerUserProfileAdGroup. | Нет |
CpmVideoAdGroup | CpmVideoAdGroupAdd | Параметры группы медийных видеообъявлений (в кампании с типом «Медийная кампания»). Чтобы создать такую группу, укажите пустую структуру CpmVideoAdGroup. | Нет |
SmartAdGroup | SmartAdGroupAdd | Параметры группы смарт-баннеров. | Нет |
UnifiedAdGroup | UnifiedAdGroupAdd | Параметры единой перфоманс группы. См. Тип группы. | Нет |
TextAdGroupFeedParams | TextAdGroupFeedParams | Параметры фида и идентификаторы категорий для группы текстово-графических объявлений. | Нет |
Структура MobileAppAdGroupAdd | |||
StoreUrl | string | Ссылка на приложение в магазине приложений AppStore или Google Play (не более 1024 символов). Должна содержать протокол. Недоступна для изменения. См. раздел Ссылка на приложение в магазине приложений помощи Директа. Ограничение. Во всех группах объявлений одной кампании должна быть указана одинаковая ссылка на приложение. Если в кампании ранее были созданы группы с разными ссылками на приложение, то при добавлении разрешено указать ссылку на приложение, которое отображается в параметрах кампании в веб-интерфейсе Директа. | Да |
TargetDeviceType | array of DeviceTypeEnum | На каких устройствах показывать объявления:
| Да |
TargetCarrier | CarrierEnum | По каким типам подключения к интернету показывать объявления:
| Да |
TargetOperatingSystemVersion | string | Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3. Примечание. Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше. | Да |
Структура DynamicTextAdGroupAdd | |||
DomainUrl | string | Доменное имя сайта, для которого требуется сгенерировать динамические объявления (не более 100 символов). Протокол указывать не нужно. | Да |
AutotargetingCategories | array of AutotargetingCategoriesAddItem | Категории таргетинга, которые требуется добавить. | Нет |
Структура DynamicTextFeedAdGroupAdd | |||
FeedId | long | Идентификатор фида, на основе которого требуется сгенерировать динамические объявления. | Да |
AutotargetingCategories | array of AutotargetingCategoriesAddItem | Категории таргетинга, которые требуется добавить. | Нет |
Структура AutotargetingCategoriesAddItem | |||
Category | AutotargetingCategoriesEnum | Категория таргетинга:
| Да |
Value | YesNoEnum | Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. | Да |
Структура SmartAdGroupAdd | |||
FeedId | long | Идентификатор фида, на основе которого требуется сгенерировать смарт-баннеры. | Да |
AdTitleSource | string | Название элемента фида, из которого нужно брать заголовок объявления. Если не задано, заголовок генерируется автоматически. | Нет |
AdBodySource | string | Название элемента фида, из которого нужно брать текст объявления. Если не задано, текст генерируется автоматически. | Нет |
Структура UnifiedAdGroupAdd | |||
OfferRetargeting | YesNoEnum | Признак включения офферного ретаргетинга. | Да |
Структура TextAdGroupFeedParamsAdd | |||
FeedId | long | Идентификатор фида, на основе которого требуется сгенерировать текстово-графические объявления. | Да |
FeedCategoryIds | ArrayOfLong | Идентификаторы категорий товаров, на основе которых требуется сгенерировать текстово-графические объявления. Если идентификаторы категорий не заданы, используются все категории из фида. | Нет |
Ответ
Структура ответа в формате JSON:
{
"result": { /* result */
"AddResults": [{ /* ActionResult */
"Id": (long),
"Warnings": [{ /* ExceptionNotification */
"Code": (int), /* required */
"Message": (string), /* required */
"Details": (string)
}, ... ],
"Errors": [{ /* ExceptionNotification */
"Code": (int), /* required */
"Message": (string), /* required */
"Details": (string)
}, ... ]
}, ... ]
}
}
Параметр | Тип | Описание |
Структура result (для JSON) / AddResponse (для SOAP) | ||
---|---|---|
AddResults | array of ActionResult | Результаты добавления групп. |
Структура ActionResult | ||
Id | long | Идентификатор созданной группы. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов. |
Warnings | array of ExceptionNotification | Предупреждения, возникшие при выполнении операции. |
Errors | array of ExceptionNotification | Ошибки, возникшие при выполнении операции. |
Параметр | Тип | Описание |
Структура result (для JSON) / AddResponse (для SOAP) | ||
---|---|---|
AddResults | array of ActionResult | Результаты добавления групп. |
Структура ActionResult | ||
Id | long | Идентификатор созданной группы. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов. |
Warnings | array of ExceptionNotification | Предупреждения, возникшие при выполнении операции. |
Errors | array of ExceptionNotification | Ошибки, возникшие при выполнении операции. |
Примеры
- Пример запроса
-
{ "method" : "add", "params" : { "AdGroups" : [ { "RegionIds" : [ 0 ], "CampaignId" : 7273721, "NegativeKeywords" : { "Items" : [ "куплю" ] }, "Name" : "AdGroup #1" }, { "RegionIds" : [ 225 ], "CampaignId" : 4193065, "NegativeKeywords" : { "Items" : [ "продам" ] }, "Name" : "AdGroup #2" } ] } }
- Пример ответа
-
{ "result" : { "AddResults" : [ { "Id" : 636056397 }, { "Id" : 636056402 } ] } }
- Пример ответа с ошибкой
-
{ "result" : { "AddResults" : [ { "Errors" : [ { "Code" : 8800, "Details" : "Campaign not found", "Message" : "Object not found" } ] }, { "Errors" : [ { "Code" : 5120, "Details" : "221 invalid or non-existent region", "Message" : "Geo-targeting not set up properly" } ] } ] } }