--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://yandex.ru/dev/direct/doc/en/adgroups/add.md - https://yandex.ru/dev/direct/doc/ru/adgroups/add.md sourcePath: ru/ref-v5/adgroups/add.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/direct/doc/ru/llms.txt # add Создает группы объявлений. ## Узнайте больше - [Как работает метод add](https://yandex.ru/dev/direct/doc/dg/best-practice/modify.html) - [Как обрабатывать ошибки](https://yandex.ru/dev/direct/doc/dg/concepts/errors.html) ## Ограничения {#restrictions} Для работы с Единой перфоманс-группой используется адрес `https://api.direct.yandex.com/v501/`. Не допускается добавление группы в архивную кампанию. Не более 1000 групп в одном вызове метода. Ограничение на количество групп объявлений в кампании для пользователя можно получить с помощью метода [Clients](https://yandex.ru/dev/direct/doc/ru/clients/clients.md).[get](https://yandex.ru/dev/direct/doc/ru/clients/get.md) или [AgencyClients](https://yandex.ru/dev/direct/doc/ru/agencyclients/agencyclients.md).[get](https://yandex.ru/dev/direct/doc/ru/agencyclients/get.md) (элемент ADGROUPS_TOTAL_PER_CAMPAIGN массива Restrictions). ## Запрос {#input} Структура запроса в формате JSON: ```javascript translate=no { "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](https://yandex.ru/dev/direct/doc/ru/dictionaries/dictionaries.md).[get](https://yandex.ru/dev/direct/doc/ru/dictionaries/get.md). | Да || || `NegativeKeywords` | ArrayOfString | Массив минус-фраз, общих для всех ключевых фраз группы объявлений. {% note alert %} Минус-фразы не допускаются в группе медийных объявлений с условием нацеливания по профилю пользователей. {% endnote %} Минус-фразу следует указывать без минуса перед первым словом. Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — не более 4096 символов. Пробелы, дефисы и операторы не учитываются в суммарной длине. {% note info %} Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании. {% endnote %} | Нет || || `NegativeKeywordSharedSetIds` | ArrayOfLong | Идентификаторы наборов минус-фраз. Не более 3 элементов в массиве. Получить идентификаторы наборов можно с помощью метода [NegativeKeywordSharedSets](https://yandex.ru/dev/direct/doc/ru/negativekeywordsharedsets/negativekeywordsharedsets.md).[get](https://yandex.ru/dev/direct/doc/ru/negativekeywordsharedsets/get.md). {% note alert %} Минус-фразы не допускаются в группе медийных объявлений с условием нацеливания по профилю пользователей. {% endnote %} | Нет || || `TrackingParams` | string | GET-параметры для отслеживания источников переходов на сайт, которые добавляются в ссылку всех объявлений группы (не более 1024 символов). Могут содержать [подстановочные переменные](https://yandex.ru/support/direct/statistics/url-tags.html). Например: 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 | Параметры единой перфоманс группы. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). | Нет || || `TextAdGroupFeedParams` | TextAdGroupFeedParams | Параметры фида и идентификаторы категорий для группы текстово-графических объявлений. | Нет || || **Структура MobileAppAdGroupAdd** | > | > | > || || `StoreUrl` | string | Ссылка на приложение в магазине приложений AppStore или Google Play (не более 1024 символов). Должна содержать протокол. Недоступна для изменения. См. раздел [Ссылка на приложение в магазине приложений](https://yandex.ru/support/direct/products-mobile-apps-ads/app-link.html) Справки Директа. {% note alert %} Во всех группах объявлений одной кампании должна быть указана одинаковая ссылка на приложение. Если в кампании ранее были созданы группы с разными ссылками на приложение, то при добавлении разрешено указать ссылку на приложение, которое отображается в параметрах кампании в веб-интерфейсе Директа. {% endnote %} | Да || || `TargetDeviceType` | array of DeviceTypeEnum | На каких устройствах показывать объявления: - DEVICE_TYPE_MOBILE — смартфоны; - DEVICE_TYPE_TABLET — планшеты. | Да || || `TargetCarrier` | CarrierEnum | По каким типам подключения к интернету показывать объявления: - WI_FI_ONLY — только по Wi-FI; - WI_FI_AND_CELLULAR — по мобильной связи и Wi-Fi. | Да || || `TargetOperatingSystemVersion` | string | Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3. {% note info %} Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше. {% endnote %} | Да || || **Структура DynamicTextAdGroupAdd** | > | > | > || || `DomainUrl` | string | Доменное имя сайта, для которого требуется сгенерировать динамические объявления (не более 100 символов). Протокол указывать не нужно. | Да || || `AutotargetingCategories` | array of AutotargetingCategoriesAddItem | Категории таргетинга, которые требуется добавить. | Нет || || **Структура DynamicTextFeedAdGroupAdd** | > | > | > || || `FeedId` | long | Идентификатор фида, на основе которого требуется сгенерировать динамические объявления. | Да || || `AutotargetingCategories` | array of AutotargetingCategoriesAddItem | Категории таргетинга, которые требуется добавить. | Нет || || **Структура AutotargetingCategoriesAddItem** | > | > | > || || `Category` | AutotargetingCategoriesEnum | Категория таргетинга: - EXACT — целевые запросы. Объявление точно отвечает на запросы пользователя; - ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить продвигаемым. При этом объявление также может удовлетворить запрос; - COMPETITOR — запросы с упоминанием конкурентов. Поиск продвигаемого продукта у конкурентов; - BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является предложение; - ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с продвигаемым товаром или услугой. | Да || || `Value` | YesNoEnum | Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. | Да || || **Структура SmartAdGroupAdd** | > | > | > || || `FeedId` | long | Идентификатор фида, на основе которого требуется сгенерировать смарт-баннеры. | Да || || `AdTitleSource` | string | Название элемента фида, из которого нужно брать заголовок объявления. Если не задано, заголовок генерируется автоматически. | Нет || || `AdBodySource` | string | Название элемента фида, из которого нужно брать текст объявления. Если не задано, текст генерируется автоматически. | Нет || || **Структура UnifiedAdGroupAdd** | > | > | > || || `OfferRetargeting` | YesNoEnum | Признак включения офферного ретаргетинга. | Да || || **Структура TextAdGroupFeedParamsAdd** | > | > | > || || `FeedId` | long | Идентификатор фида, на основе которого требуется сгенерировать текстово-графические объявления. | Да || || `FeedCategoryIds` | ArrayOfLong | Идентификаторы категорий товаров, на основе которых требуется сгенерировать текстово-графические объявления. Если идентификаторы категорий не заданы, используются все категории из фида. | Нет || |# ## Ответ {#output} Структура ответа в формате JSON: ```javascript translate=no { "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 | Идентификатор созданной группы. Возвращается в случае отсутствия ошибок, см. раздел [Операции над массивом объектов](https://yandex.ru/dev/direct/doc/dg/best-practice/modify.html). || || `Warnings` | array of ExceptionNotification | Предупреждения, возникшие при выполнении операции. || || `Errors` | array of ExceptionNotification | Ошибки, возникшие при выполнении операции. || |# ## Примеры {#samples} **Пример запроса**   ```javascript translate=no { "method" : "add", "params" : { "AdGroups" : [ { "RegionIds" : [ 0 ], "CampaignId" : 7273721, "NegativeKeywords" : { "Items" : [ "куплю" ] }, "Name" : "AdGroup #1" }, { "RegionIds" : [ 225 ], "CampaignId" : 4193065, "NegativeKeywords" : { "Items" : [ "продам" ] }, "Name" : "AdGroup #2" } ] } } ``` **Пример ответа**   ```javascript translate=no { "result" : { "AddResults" : [ { "Id" : 636056397 }, { "Id" : 636056402 } ] } } ``` **Пример ответа с ошибкой**   ```javascript translate=no { "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" } ] } ] } } ```