add

Создает корректировки ставок.

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

Ограничения

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

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

Не более 12 корректировок по полу и возрасту для одной кампании или группы объявлений.

Не более 100 корректировок для целевой аудитории для одной кампании или группы объявлений.

Корректировки на мобильных нельзя создать для кампаний и групп объявлений для рекламы мобильных приложений.

Корректировки на компьютерах, планшетах, Smart TV можно создать только для групп медийных объявлений.

Корректировки для видеодополнений можно создать только для кампаний и групп текстово-графических объявлений.

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

Запрос

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

{
  "method": "add",
  "params": { /* params */
    "BidModifiers": [{  /* BidModifierAddItem */
      "MobileAdjustment": {  /* MobileAdjustmentAdd */
        "BidModifier": (int), /* required */
        "OperatingSystemType": ( "IOS" | "ANDROID" )
      },
      "DesktopAdjustment": {  /* DesktopAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "DemographicsAdjustments": [{  /* DemographicsAdjustmentAdd */
        "Gender": ( "GENDER_MALE" | "GENDER_FEMALE" ),
        "Age": ( "AGE_0_17" | "AGE_18_24" | "AGE_25_34" | "AGE_35_44" | "AGE_45" | "AGE_45_54" | "AGE_55" ),
        "BidModifier": (int) /* required */
      }, ... ],
      "RetargetingAdjustments": [{  /* RetargetingAdjustmentAdd */
        "RetargetingConditionId": (long), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "RegionalAdjustments": [{    /* RegionalAdjustmentAdd */
        "RegionId": (long), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "VideoAdjustment": { /* VideoAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "CampaignId": (long),
      "AdGroupId": (long)
    }, ... ] /* required */
  }
}
Параметр Тип Описание Обязательный
Структура params (для JSON) / AddRequest (для SOAP)
BidModifiers array of BidModifierAddItem

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

Да
Структура BidModifierAddItem
CampaignId long Идентификатор кампании. Указывается при создании корректировки на уровне кампании. Либо CampaignId, либо AdGroupId
AdGroupId long Идентификатор группы объявлений. Указывается при создании корректировок на уровне группы.
MobileAdjustment MobileAdjustmentAdd Корректировка на мобильных. Либо MobileAdjustment, либо DesktopAdjustment, либо DemographicsAdjustments, либо RetargetingAdjustments, либо RegionalAdjustments, либо VideoAdjustment
DesktopAdjustment DesktopAdjustmentAdd Корректировка на компьютерах, планшетах, Smart TV.
DemographicsAdjustments array of DemographicsAdjustmentAdd Корректировки по полу и возрасту. Не более 12 элементов в массиве.
RetargetingAdjustments array of RetargetingAdjustmentAdd Корректировки для целевой аудитории. Не более 100 элементов в массиве.
RegionalAdjustments array of RegionalAdjustmentAdd Корректировки по региону показа.
VideoAdjustment VideoAdjustmentAdd Корректировка для видеодополнений.
Структура MobileAdjustmentAdd
BidModifier int

Значение коэффициента к ставке для показа объявлений на мобильных телефонах.

Указывается в процентах:
  • От 0 до 1300 — для корректировок в группе медийных объявлений.
  • От 50 до 1300 — для корректировок в остальных типах кампаний и групп.
Ставка умножается на значение BidModifier/100.
Да
OperatingSystemType OperatingSystemTypeEnum

Тип операционной системы. Допускается только для корректировок в группах медийных объявлений.

Если параметр не указан, подразумевается любая операционная система.

Нет
Структура DesktopAdjustmentAdd
BidModifier int

Значение коэффициента к ставке для показа объявлений на компьютерах, планшетах, Smart TV.

Указывается в процентах от 0 до 1300. Ставка умножается на значение BidModifier/100.

В одной группе объявлений коэффициент для показа на мобильных без указания операционной системы и коэффициент для показа на компьютерах, планшетах, Smart TV не допускается устанавливать одновременно равными 0.

Да
Структура DemographicsAdjustmentAdd
Gender GenderEnum

Пол пользователя: GENDER_MALE или GENDER_FEMALE.

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

Хотя бы один из параметров Gender или Age
Age AgeRangeEnum

Возрастная группа пользователя: одно из значений AGE_0_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54 или AGE_55.

Значение AGE_45 устарело, рекомендуется создать отдельные корректировки для возрастных групп AGE_45_54 и AGE_55.

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

Внимание. Срезы аудитории, для которых задаются корректировки, не должны совпадать или пересекаться. Например, нельзя задать корректировки одновременно для групп AGE_25_34 и GENDER_MALE+AGE_25_34.
BidModifier int

Значение коэффициента к ставке для показа объявлений пользователям указанного пола и/или возрастной группы.

Указывается в процентах от 0 до 1300. Ставка умножается на значение BidModifier/100.

Да
Структура RetargetingAdjustmentAdd
RetargetingConditionId long Идентификатор условия ретаргетинга и подбора аудитории. Допускается только условие с типом RETARGETING. См. раздел Условие ретаргетинга и подбора аудитории (RetargetingList). Да
BidModifier int

Значение коэффициента к ставке для показа объявлений пользователям, отвечающим условию ретаргетинга и подбора аудитории.

Указывается в процентах от 0 до 1300. Ставка умножается на значение BidModifier/100.

Да
Структура RegionalAdjustmentAdd
RegionId long

Идентификатор региона из справочника регионов.

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

Да
BidModifier int

Значение коэффициента к ставке для показа объявлений в указанном регионе.

Указывается в процентах от 10 до 1300. Ставка умножается на значение BidModifier/100.

Да
Структура VideoAdjustmentAdd
BidModifier int

Значение коэффициента к ставке для показа объявлений с видеодополнением.

Указывается в процентах от 50 до 1300. Ставка умножается на значение BidModifier/100.

Да

Ответ

Внимание.
  • Добавление корректировок по полу и возрасту для одной кампании или группы объявлений считается единой операцией. В случае ошибки в одном из коэффициентов не будет создан ни один.

  • Добавление корректировок для целевой аудитории для одной кампании или группы объявлений считается единой операцией. В случае ошибки в одном из коэффициентов не будет создан ни один.

  • Добавление корректировок по региону показа для одной кампании считается единой операцией. В случае ошибки в одном из коэффициентов не будет создан ни один.

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

{
  "result": { /* result */
    "AddResults": [{  /* MultiIdsActionResult */
      "Ids": [(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 MultiIdsActionResult Результаты добавления корректировок.
Структура MultiIdsActionResult
Ids array of long Идентификаторы созданных корректировок. Возвращаются в случае отсутствия ошибок, см. раздел Операции над массивом объектов. Следуют в том же порядке, что и корректировки в запросе.
Warnings array of ExceptionNotification

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

Errors array of ExceptionNotification

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

Примеры

Пример запроса
{
  "method": "add",
  "params": {
    "BidModifiers": [
      { // 1. Две корректировки по полу и возрасту
        "CampaignId": 10001,
        "DemographicsAdjustments": [
          {
            "Gender": "GENDER_MALE",
            "Age": "AGE_25_34",
            "BidModifier": 101
          },
          {
            "Age": "AGE_45_54",
            "BidModifier": 140
          }
        ]
      },
      { // 2. Корректировки с пересекающимися срезами аудитории   
        "CampaignId": 10002,
        "DemographicsAdjustments": [
          {
            "Gender": "GENDER_MALE",
            "Age": "AGE_25_34",
            "BidModifier": 120
          },
          {
            "Age": "AGE_25_34",
            "BidModifier": 170
          }
        ]
      }, 
      { // 3. Недопустимое значение коэффициента
        "CampaignId": 10003,
        "DemographicsAdjustments": [
          {
            "Gender": "GENDER_MALE",
            "Age": "AGE_25_34",
            "BidModifier": 120
          },
          {
            "Gender": "GENDER_FEMALE",
            "Age": "AGE_35_44",
            "BidModifier": 10000
          }
        ]
      },
      { // 4. Корректировка для целевой аудитории на уровне группы объявлений
        "AdGroupId": 500001,
        "RetargetingAdjustments": [
          {
            "RetargetingConditionId": 2004,
            "BidModifier": 201
          }
        ]
      }
    ]
  }
}
Пример ответа
{
  "result" : {
    "AddResults" : [
      { // 1. Созданы две корректировки по полу и возрасту
        "Ids": [ 1003, 1004 ]
      },
      { // 2. Пересекающиеся срезы - ни одна корректировка не создана
        "Errors": [
          {
            "Code": 6000,
            "Message": "Неконсистентное состояние объекта",
            "Details": "Пересекаются условия корректировок в наборе"
          }
        ]
      },
      { // 3. Недопустимое значение - ни одна корректировка не создана
        "Errors": [
          {
            "Code": 5005,
            "Message": "Поле задано неверно",
            "Details": "Значение коэффициента не может быть больше 1300"
          }
        ]
      },
      { // 4. Создана корректировка для целевой аудитории на уровне группы объявлений
        "Ids": [ 1005 ]
      }
    ]
  }
}