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

На каких устройствах показывать объявления:

  • DEVICE_TYPE_MOBILE — смартфоны;

  • DEVICE_TYPE_TABLET — планшеты.

Да

TargetCarrier

CarrierEnum

По каким типам подключения к интернету показывать объявления:

  • WI_FI_ONLY — только по Wi-FI;
  • WI_FI_AND_CELLULAR — по мобильной связи и Wi-Fi.

Да

TargetOperatingSystemVersion

string

Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3.

Примечание

Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше.

Да

Структура 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

Идентификаторы категорий товаров, на основе которых требуется сгенерировать текстово-графические объявления.

Если идентификаторы категорий не заданы, используются все категории из фида.

Нет

Ответ

Структура ответа в формате 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

Ошибки, возникшие при выполнении операции.

Примеры

Пример запроса

{
  "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"
          }
        ]
      }
    ]
  }
}
Предыдущая
AdGroups: операции с группами объявлений
Следующая
delete