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 ...
      },
      "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)
Campaignsarray of CampaignAddItem

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

Да
Структура CampaignAddItem
ClientInfostringНазвание клиента (до 255 символов). Значение по умолчанию — наименование из настроек рекламодателя.Нет
NotificationNotificationНастройки SMS- и email-уведомлений.Нет
TimeZonestring

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

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

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

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

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

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

Да
DailyBudgetDailyBudget

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

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

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

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

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

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

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

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

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

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

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

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

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

Нет
TextCampaignTextCampaignAddItemНастройки для кампании с типом «Текстово-графические объявления». Описание структуры данных см. в разделе add: параметры TextCampaign.Либо TextCampaign, либо MobileAppCampaign, либо DynamicTextCampaign, либо CpmBannerCampaign
MobileAppCampaignMobileAppCampaignAddItemНастройки для кампании с типом «Реклама мобильных приложений». Описание структуры данных см. в разделе add: параметры MobileAppCampaign.
DynamicTextCampaignDynamicTextCampaignAddItemНастройки для кампании с типом «Динамические объявления». Описание структуры данных см. в разделе add: параметры DynamicTextCampaign.
CpmBannerCampaignCpmBannerCampaignAddItemНастройки для кампании с типом «Медийная кампания». Описание структуры данных см. в разделе add: параметры CpmBannerCampaign.
TimeTargetingTimeTargetingAddНастройки временного таргетинга и почасовой корректировки ставок. Указываются по времени часового пояса, указанного в параметре TimeZone.Нет
Структура Notification
SmsSettingsSmsSettings

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

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

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

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

Нет
TimeTostring

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

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

Нет
Структура EmailSettings
Emailstring

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

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

Нет
CheckPositionIntervalint

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

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

Нет
WarningBalanceint

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

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

Нет
SendAccountNewsYesNoEnum

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

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

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

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

Да
ModeDailyBudgetModeEnum

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

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

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

Да
Структура TimeTargetingAdd
ScheduleArrayOfString

Настройки временного таргетинга и почасовой корректировки ставок. Не более 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).
Нет
ConsiderWorkingWeekendsYesNoEnum

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

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

Да
HolidaysScheduleTimeTargetingOnPublicHolidays

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

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

Нет
Структура TimeTargetingOnPublicHolidays
SuspendOnHolidaysYesNoEnum

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

Примечание. Параметры BidPercent, StartHour и EndHour допускается задавать только при значении NO параметра SuspendOnHolidays.
Да
BidPercentintКоэффициент к ставке при показе в праздничные нерабочие дни. Указывается в процентах от 10 до 200, значение должно быть кратно 10.Нет
StartHourintВремя (в часах) начала показов в праздничные нерабочие дни. От 0 до 23.При значении NO параметра SuspendOnHolidays
EndHourintВремя (в часах) окончания показов в праздничные нерабочие дни. От 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)
AddResultsarray of ActionResultРезультаты добавления кампаний.
Структура ActionResult
IdlongИдентификатор созданной кампании. Возвращается в случае отсутствия ошибок, см. раздел Операции над массивом объектов.
Warningsarray of ExceptionNotification

Предупреждения, возникшие при выполнении операции.

Errorsarray of ExceptionNotification

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