add

Создает группы объявлений.

  1. Ограничения
  2. Запрос
  3. Ответ
  4. Примеры

Ограничения

Не допускается добавление группы в архивную кампанию.

Не более 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 */
      },
      "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 */
      },
      "CpmBannerKeywordsAdGroup": {  /* CpmBannerKeywordsAdGroupAdd */
      },
      "CpmBannerUserProfileAdGroup": {  /* CpmBannerUserProfileAdGroupAdd */
      }
    }, ... ] /* 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 символов. Пробелы, дефисы и операторы не учитываются в суммарной длине.

Примечание. Минус-фразы, общие для всех групп в кампании, предпочтительно задавать в одноименном параметре кампании.
Нет
TrackingParams string

GET-параметры для отслеживания источников переходов на сайт, которые добавляются в ссылку всех объявлений группы (не более 1024 символов). Могут содержать подстановочные переменные.

Например: from=direct&ad={ad_id}

Параметр можно указать для группы любого типа, однако в настоящее время он используется только для групп динамических объявлений. Для других типов групп указанные GET-параметры в ссылку не добавляются.

Нет
MobileAppAdGroup MobileAppAdGroupAdd Параметры группы объявлений для рекламы мобильных приложений. Нет
DynamicTextAdGroup DynamicTextAdGroupAdd Параметры группы динамических объявлений. Нет
CpmBannerKeywordsAdGroup CpmBannerKeywordsAdGroupAdd Параметры группы медийных объявлений с ключевыми фразами. Чтобы создать такую группу, укажите пустую структуру CpmBannerKeywordsAdGroup. Нет
CpmBannerUserProfileAdGroup CpmBannerUserProfileAdGroupAdd Параметры группы медийных объявлений с условием нацеливания по профилю пользователей. Чтобы создать такую группу, укажите пустую структуру CpmBannerUserProfileAdGroup. Нет
Структура 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 символов). Протокол указывать не нужно. Да

Ответ

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