add

Создает кампании.

  1. Ограничения
  2. Запрос
  3. Ответ
Внимание. Все денежные параметры кампаний (дневной бюджет, недельный бюджет, средняя цена для автоматических стратегий) передаются через API Директа в виде целых чисел. Передаваемое значение представляет собой денежное значение в валюте рекламодателя, умноженное на 1 000 000.

Ограничения

Ограничение на количество кампаний для рекламодателя можно получить с помощью метода Clients.get или AgencyClients.get (элементы CAMPAIGNS_TOTAL_PER_CLIENT и CAMPAIGNS_UNARCHIVED_PER_CLIENT массива Restrictions).

Не более 10 кампаний в одном вызове метода.

Запрос

Структура запроса в формате JSON:

{
  "method": "add",
  "params": { /* params */
    "Campaigns": [{  /* CampaignAddItem */
      "ClientInfo": (string),
      "Notification": {  /* Notification */
        "SmsSettings": {  /* SmsSettings */
          "Events": [( "MONITORING" | ... | "FINISHED" ), ... ],
          "TimeFrom": (string),
          "TimeTo": (string)
        },
        "EmailSettings": {  /* EmailSettings */
          "Email": (string),
          "CheckPositionInterval": (int),
          "WarningBalance": (int),
          "SendAccountNews": ( "YES" | "NO" ),
          "SendWarnings": ( "YES" | "NO" )
        }
      },
      "TimeZone": (string),
      "Name": (string), /* required */
      "StartDate": (string), /* required */
      "DailyBudget": {  /* DailyBudget */
        "Amount": (long), /* required */
        "Mode": ( "STANDARD" | "DISTRIBUTED" ) /* required */
      },
      "EndDate": (string),
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      },
      "BlockedIps": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      },
      "ExcludedSites": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      },
      "TextCampaign": {  /* TextCampaignAddItem */
        ... text campaign params ...
      },
      "MobileAppCampaign": {  /* MobileAppCampaignAddItem */
        ... mobile app campaign params ...
      },
      "DynamicTextCampaign": {  /* DynamicTextCampaignAddItem */
        ... dynamic text campaign params ...
      },
      "CpmBannerCampaign": {  /* CpmBannerCampaignAddItem */
        ... cpm banner campaign params ...
      },
      "SmartCampaign": {  /* SmartCampaignAddItem */
        ... smart campaign params ...
      },
      "UnifiedCampaign": {  /* UnifiedCampaignAddItem */
        ... unified campaign params ...
      },
      "TimeTargeting": {  /* TimeTargetingAdd */
        "Schedule": {  /* ArrayOfString */
          "Items": [(string), ... ] /* required */
        },
        "ConsiderWorkingWeekends": ( "YES" | "NO" ), /* required */
        "HolidaysSchedule": {  /* TimeTargetingOnPublicHolidays */
          "SuspendOnHolidays": ( "YES" | "NO" ), /* required */
          "BidPercent": (int),
          "StartHour": (int),
          "EndHour": (int)
        }
      }
    }, ...] /* required */
  }
}
Параметр Тип Описание Обязательный
Структура params (для JSON) / AddRequest (для SOAP)
Campaigns array of CampaignAddItem

Кампании, которые требуется добавить.

Да
Структура CampaignAddItem
ClientInfo string Название клиента (до 255 символов). Значение по умолчанию — наименование из настроек рекламодателя. Нельзя задать для UnifiedCampaign. Нет
Notification Notification Настройки SMS- и email-уведомлений. Нельзя задать для UnifiedCampaign. Нет
TimeZone string

Часовой пояс в месте нахождения рекламодателя. Справочник часовых поясов можно получить с помощью метода Dictionaries.get.

Значение по умолчанию Europe/Moscow.

Нет
Name string Название кампании (до 255 символов). Да
StartDate string

Дата начала показов объявлений в формате YYYY-MM-DD. Должна быть не меньше текущей даты.

Показы объявлений начинаются в 00:00 по московскому времени (независимо от значения параметра TimeZone). На время начала показов влияют настройки временного таргетинга (параметр TimeTargeting).

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

Если для кампании установлен бюджет на период, значение этого поля игнорируется, приоритет – у периода стратегии.

Да
DailyBudget DailyBudget

Настройки дневного бюджета кампании.

Управление дневным бюджетом доступно, если в кампании выбрана ручная стратегия показа. В противном случае при попытке задать дневной бюджет возвращается ошибка.

Нет
EndDate string Дата окончания показов объявлений в формате YYYY-MM-DD. Показы объявлений прекращаются в 24:00 по московскому времени (независимо от значения параметра TimeZone). Нет
NegativeKeywords ArrayOfString

Массив минус-фраз, общих для всех ключевых фраз кампании.

Ограничение. Для кампаний с типом «Медийная кампания» параметр не поддерживается.

Минус-фразу следует указывать без минуса перед первым словом.

Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — 20000 символов. Пробелы, дефисы и операторы не учитываются в суммарной длине.

Нет
BlockedIps ArrayOfString Массив IP-адресов, которым не нужно показывать объявления. Не более 25 элементов в массиве. Нет
ExcludedSites ArrayOfString

Массив мест показа, где не нужно показывать объявления:

  • доменные имена сайтов;

  • идентификаторы мобильных приложений (bundle ID для iOS, package name для Android);

  • наименования внешних сетей (SSP). Список наименований можно получить с помощью метода Dictionaries.get.

Не более 1000 элементов в массиве. Не более 255 символов в каждом элементе массива.

Нет
TextCampaign TextCampaignAddItem Настройки для кампании с типом «Текстово-графические объявления». Описание структуры данных см. в разделе add: параметры TextCampaign. Либо TextCampaign, либо MobileAppCampaign, либо DynamicTextCampaign, либо CpmBannerCampaign, либо SmartCampaign
MobileAppCampaign MobileAppCampaignAddItem Настройки для кампании с типом «Реклама мобильных приложений». Описание структуры данных см. в разделе add: параметры MobileAppCampaign.
DynamicTextCampaign DynamicTextCampaignAddItem Настройки для кампании с типом «Динамические объявления». Описание структуры данных см. в разделе add: параметры DynamicTextCampaign.
CpmBannerCampaign CpmBannerCampaignAddItem Настройки для кампании с типом «Медийная кампания». Описание структуры данных см. в разделе add: параметры CpmBannerCampaign.
SmartCampaign SmartCampaignAddItem Настройки для кампании с типом «Смарт-баннеры». Описание структуры данных см. в разделе add: параметры SmartCampaign.
UnifiedCampaign UnifiedCampaignAddItem Настройки для кампании с типом «Единая перфоманс кампания». Описание структуры данных см. в разделе add: параметры UnifiedCampaign.
TimeTargeting TimeTargetingAdd Настройки временного таргетинга и почасовой корректировки ставок. Указываются по времени часового пояса, указанного в параметре TimeZone. Нет
Структура Notification
SmsSettings SmsSettings

Настройки отправки SMS-уведомлений. Телефонный номер для отправки берется из профиля рекламодателя на Яндексе (см. раздел Мои телефоны помощи Яндекс Паспорта).

Нет
EmailSettings EmailSettings Настройки отправки уведомлений по электронной почте. Нет
Структура SmsSettings
Events array of SmsEventsEnum
События, о которых необходимо информировать по SMS:
  • MONITORING — остановка и возобновление показов объявлений мониторингом доступности сайта по данным Метрики;
  • MODERATION — объявления приняты или отклонены модерацией;
  • MONEY_IN — поступление средств на баланс кампании (не используется при подключенном общем счете);
  • MONEY_OUT — исчерпание средств на балансе кампании (не используется при подключенном общем счете);
  • FINISHED — окончание кампании.
Нет
TimeFrom string

Время, начиная с которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Значение по умолчанию 9:00.

Нет
TimeTo string

Время, до которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Значение по умолчанию 21:00.

Нет
Структура EmailSettings
Email string

Адрес электронной почты для отправки уведомлений о событиях, связанных с кампанией.

Значение по умолчанию — адрес рекламодателя.

Нет
CheckPositionInterval int

Периодичность проверки прогноза трафика — 15, 30 или 60 минут. Значение по умолчанию — 60.

Уведомление отправляется, если прогноз трафика стал ниже того, который обеспечивала ставка на момент установки.

Нет
WarningBalance int

Минимальный баланс, при уменьшении до которого отправляется уведомление. Задается в процентах от суммы последнего платежа, от 1 до 50. Значение по умолчанию — 20.

Если у клиента подключен общий счет, параметр не используется.

Нет
SendAccountNews YesNoEnum

Отправлять ли уведомления о событиях, связанных с кампанией. Задается для кампаний, обслуживаемых персональным менеджером в Яндексе. Для кампаний, не обслуживаемых персональным менеджером, переданное значение игнорируется. Значение по умолчанию — NO.

Нет
SendWarnings YesNoEnum Отправлять ли уведомления по электронной почте. Значение по умолчанию — NO. Нет
Структура DailyBudget
Amount long

Дневной бюджет кампании в валюте рекламодателя, умноженный на 1 000 000.

Минимальный дневной бюджет для каждой валюты представлен в справочнике валют. Справочник валют можно получить с помощью метода Dictionaries.get.

Да
Mode DailyBudgetModeEnum

Режим показа объявлений:

  • STANDARD — стандартный.
  • DISTRIBUTED — распределенный.

См. подраздел Средний дневной бюджет раздела «Ручное управление ставками» помощи Директа.

Да
Структура TimeTargetingAdd
Schedule ArrayOfString

Настройки временного таргетинга и почасовой корректировки ставок. Не более 7 элементов в массиве.

Каждый элемент массива содержит 25 чисел, разделенных запятыми. Первое число — номер дня недели: от 1 (понедельник) до 7 (воскресенье). Следующие 24 числа — последовательность коэффициентов к ставке для показа объявлений в соответствующие часы. Коэффициенты указываются в процентах от 0 до 200, значение должно быть кратно 10. Коэффициент 0 означает, что объявления в этот час не показываются. Пример элемента массива: 1, 0, 0, 50, 50, 100, 100, 150, 200, 200, 150, 100, 100, 80, 70, 100, 100, 100, 50, 50, 40, 30, 0, 0, 0

Примечание.
  • Если в массиве не указан элемент, соответствующий дню недели, то для этого дня все коэффициенты устанавливаются равными 100.
  • Если выбрана автоматическая стратегия показа, коэффициент 0 означает запрет показов, а любой другой коэффициент означает разрешение показов (то есть эквивалентен 100).
Нет
ConsiderWorkingWeekends YesNoEnum

Менять ли расписание показов при переносе рабочего дня на субботу или воскресенье.

Например, если рабочий день перенесен с понедельника на субботу, при значении YES в рабочую субботу пойдут показы по расписанию понедельника, а в нерабочий понедельник, — по расписанию субботы.

Да
HolidaysSchedule TimeTargetingOnPublicHolidays

Настройки показа в праздничные дни.

Если часовой пояс, указанный в параметре TimeZone, относится к России, Украине, Беларуси, Казахстану или Турции, то используется календарь праздников и переносов рабочих дней соответствующей страны. В остальных случаях используется российский календарь.

Нет
Структура TimeTargetingOnPublicHolidays
SuspendOnHolidays YesNoEnum

Останавливать ли объявления в праздничные нерабочие дни: YES — останавливать, NO — не останавливать.

Примечание. Параметры BidPercent, StartHour и EndHour допускается задавать только при значении NO параметра SuspendOnHolidays.
Да
BidPercent int Коэффициент к ставке при показе в праздничные нерабочие дни. Указывается в процентах от 10 до 200, значение должно быть кратно 10. Нет
StartHour int Время (в часах) начала показов в праздничные нерабочие дни. От 0 до 23. При значении NO параметра SuspendOnHolidays
EndHour int Время (в часах) окончания показов в праздничные нерабочие дни. От 1 до 24. При значении NO параметра SuspendOnHolidays
Параметр Тип Описание Обязательный
Структура params (для JSON) / AddRequest (для SOAP)
Campaigns array of CampaignAddItem

Кампании, которые требуется добавить.

Да
Структура CampaignAddItem
ClientInfo string Название клиента (до 255 символов). Значение по умолчанию — наименование из настроек рекламодателя. Нельзя задать для UnifiedCampaign. Нет
Notification Notification Настройки SMS- и email-уведомлений. Нельзя задать для UnifiedCampaign. Нет
TimeZone string

Часовой пояс в месте нахождения рекламодателя. Справочник часовых поясов можно получить с помощью метода Dictionaries.get.

Значение по умолчанию Europe/Moscow.

Нет
Name string Название кампании (до 255 символов). Да
StartDate string

Дата начала показов объявлений в формате YYYY-MM-DD. Должна быть не меньше текущей даты.

Показы объявлений начинаются в 00:00 по московскому времени (независимо от значения параметра TimeZone). На время начала показов влияют настройки временного таргетинга (параметр TimeTargeting).

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

Если для кампании установлен бюджет на период, значение этого поля игнорируется, приоритет – у периода стратегии.

Да
DailyBudget DailyBudget

Настройки дневного бюджета кампании.

Управление дневным бюджетом доступно, если в кампании выбрана ручная стратегия показа. В противном случае при попытке задать дневной бюджет возвращается ошибка.

Нет
EndDate string Дата окончания показов объявлений в формате YYYY-MM-DD. Показы объявлений прекращаются в 24:00 по московскому времени (независимо от значения параметра TimeZone). Нет
NegativeKeywords ArrayOfString

Массив минус-фраз, общих для всех ключевых фраз кампании.

Ограничение. Для кампаний с типом «Медийная кампания» параметр не поддерживается.

Минус-фразу следует указывать без минуса перед первым словом.

Не более 7 слов в минус-фразе. Длина каждого слова — не более 35 символов. Суммарная длина минус-фраз в массиве — 20000 символов. Пробелы, дефисы и операторы не учитываются в суммарной длине.

Нет
BlockedIps ArrayOfString Массив IP-адресов, которым не нужно показывать объявления. Не более 25 элементов в массиве. Нет
ExcludedSites ArrayOfString

Массив мест показа, где не нужно показывать объявления:

  • доменные имена сайтов;

  • идентификаторы мобильных приложений (bundle ID для iOS, package name для Android);

  • наименования внешних сетей (SSP). Список наименований можно получить с помощью метода Dictionaries.get.

Не более 1000 элементов в массиве. Не более 255 символов в каждом элементе массива.

Нет
TextCampaign TextCampaignAddItem Настройки для кампании с типом «Текстово-графические объявления». Описание структуры данных см. в разделе add: параметры TextCampaign. Либо TextCampaign, либо MobileAppCampaign, либо DynamicTextCampaign, либо CpmBannerCampaign, либо SmartCampaign
MobileAppCampaign MobileAppCampaignAddItem Настройки для кампании с типом «Реклама мобильных приложений». Описание структуры данных см. в разделе add: параметры MobileAppCampaign.
DynamicTextCampaign DynamicTextCampaignAddItem Настройки для кампании с типом «Динамические объявления». Описание структуры данных см. в разделе add: параметры DynamicTextCampaign.
CpmBannerCampaign CpmBannerCampaignAddItem Настройки для кампании с типом «Медийная кампания». Описание структуры данных см. в разделе add: параметры CpmBannerCampaign.
SmartCampaign SmartCampaignAddItem Настройки для кампании с типом «Смарт-баннеры». Описание структуры данных см. в разделе add: параметры SmartCampaign.
UnifiedCampaign UnifiedCampaignAddItem Настройки для кампании с типом «Единая перфоманс кампания». Описание структуры данных см. в разделе add: параметры UnifiedCampaign.
TimeTargeting TimeTargetingAdd Настройки временного таргетинга и почасовой корректировки ставок. Указываются по времени часового пояса, указанного в параметре TimeZone. Нет
Структура Notification
SmsSettings SmsSettings

Настройки отправки SMS-уведомлений. Телефонный номер для отправки берется из профиля рекламодателя на Яндексе (см. раздел Мои телефоны помощи Яндекс Паспорта).

Нет
EmailSettings EmailSettings Настройки отправки уведомлений по электронной почте. Нет
Структура SmsSettings
Events array of SmsEventsEnum
События, о которых необходимо информировать по SMS:
  • MONITORING — остановка и возобновление показов объявлений мониторингом доступности сайта по данным Метрики;
  • MODERATION — объявления приняты или отклонены модерацией;
  • MONEY_IN — поступление средств на баланс кампании (не используется при подключенном общем счете);
  • MONEY_OUT — исчерпание средств на балансе кампании (не используется при подключенном общем счете);
  • FINISHED — окончание кампании.
Нет
TimeFrom string

Время, начиная с которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Значение по умолчанию 9:00.

Нет
TimeTo string

Время, до которого разрешено отправлять SMS о событиях, связанных с кампанией. Указывается в формате HH:MM, минуты задают кратно 15 (0, 15, 30, 45). Например, 19:45.

Значение по умолчанию 21:00.

Нет
Структура EmailSettings
Email string

Адрес электронной почты для отправки уведомлений о событиях, связанных с кампанией.

Значение по умолчанию — адрес рекламодателя.

Нет
CheckPositionInterval int

Периодичность проверки прогноза трафика — 15, 30 или 60 минут. Значение по умолчанию — 60.

Уведомление отправляется, если прогноз трафика стал ниже того, который обеспечивала ставка на момент установки.

Нет
WarningBalance int

Минимальный баланс, при уменьшении до которого отправляется уведомление. Задается в процентах от суммы последнего платежа, от 1 до 50. Значение по умолчанию — 20.

Если у клиента подключен общий счет, параметр не используется.

Нет
SendAccountNews YesNoEnum

Отправлять ли уведомления о событиях, связанных с кампанией. Задается для кампаний, обслуживаемых персональным менеджером в Яндексе. Для кампаний, не обслуживаемых персональным менеджером, переданное значение игнорируется. Значение по умолчанию — NO.

Нет
SendWarnings YesNoEnum Отправлять ли уведомления по электронной почте. Значение по умолчанию — NO. Нет
Структура DailyBudget
Amount long

Дневной бюджет кампании в валюте рекламодателя, умноженный на 1 000 000.

Минимальный дневной бюджет для каждой валюты представлен в справочнике валют. Справочник валют можно получить с помощью метода Dictionaries.get.

Да
Mode DailyBudgetModeEnum

Режим показа объявлений:

  • STANDARD — стандартный.
  • DISTRIBUTED — распределенный.

См. подраздел Средний дневной бюджет раздела «Ручное управление ставками» помощи Директа.

Да
Структура TimeTargetingAdd
Schedule ArrayOfString

Настройки временного таргетинга и почасовой корректировки ставок. Не более 7 элементов в массиве.

Каждый элемент массива содержит 25 чисел, разделенных запятыми. Первое число — номер дня недели: от 1 (понедельник) до 7 (воскресенье). Следующие 24 числа — последовательность коэффициентов к ставке для показа объявлений в соответствующие часы. Коэффициенты указываются в процентах от 0 до 200, значение должно быть кратно 10. Коэффициент 0 означает, что объявления в этот час не показываются. Пример элемента массива: 1, 0, 0, 50, 50, 100, 100, 150, 200, 200, 150, 100, 100, 80, 70, 100, 100, 100, 50, 50, 40, 30, 0, 0, 0

Примечание.
  • Если в массиве не указан элемент, соответствующий дню недели, то для этого дня все коэффициенты устанавливаются равными 100.
  • Если выбрана автоматическая стратегия показа, коэффициент 0 означает запрет показов, а любой другой коэффициент означает разрешение показов (то есть эквивалентен 100).
Нет
ConsiderWorkingWeekends YesNoEnum

Менять ли расписание показов при переносе рабочего дня на субботу или воскресенье.

Например, если рабочий день перенесен с понедельника на субботу, при значении YES в рабочую субботу пойдут показы по расписанию понедельника, а в нерабочий понедельник, — по расписанию субботы.

Да
HolidaysSchedule TimeTargetingOnPublicHolidays

Настройки показа в праздничные дни.

Если часовой пояс, указанный в параметре TimeZone, относится к России, Украине, Беларуси, Казахстану или Турции, то используется календарь праздников и переносов рабочих дней соответствующей страны. В остальных случаях используется российский календарь.

Нет
Структура TimeTargetingOnPublicHolidays
SuspendOnHolidays YesNoEnum

Останавливать ли объявления в праздничные нерабочие дни: YES — останавливать, NO — не останавливать.

Примечание. Параметры BidPercent, StartHour и EndHour допускается задавать только при значении NO параметра SuspendOnHolidays.
Да
BidPercent int Коэффициент к ставке при показе в праздничные нерабочие дни. Указывается в процентах от 10 до 200, значение должно быть кратно 10. Нет
StartHour int Время (в часах) начала показов в праздничные нерабочие дни. От 0 до 23. При значении NO параметра SuspendOnHolidays
EndHour int Время (в часах) окончания показов в праздничные нерабочие дни. От 1 до 24. При значении NO параметра SuspendOnHolidays

Ответ

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

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