add

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

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

Ограничения

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

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

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

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

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

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

Корректировки по региону показов можно задать только на уровне кампании.

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

Запрос

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

{
  "method": "add",
  "params": { /* params */
    "BidModifiers": [{  /* BidModifierAddItem */
      "MobileAdjustment": {  /* MobileAdjustmentAdd */
        "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)
BidModifiersarray of BidModifierAddItem

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

Да
Структура BidModifierAddItem
CampaignIdlongИдентификатор кампании. Указывается при создании корректировки на уровне кампании.Либо CampaignId, либо AdGroupId
AdGroupIdlongИдентификатор группы объявлений. Указывается при создании корректировок на уровне группы.
MobileAdjustmentMobileAdjustmentAddКорректировка на мобильных.Либо MobileAdjustment, либо VideoAdjustment, либо DemographicsAdjustments, либо RetargetingAdjustments, либо RegionalAdjustments
DemographicsAdjustmentsarray of DemographicsAdjustmentAddКорректировки по полу и возрасту. Не более 12 элементов в массиве.
RetargetingAdjustmentsarray of RetargetingAdjustmentAddКорректировки для посетивших сайт. Не более 100 элементов в массиве.
RegionalAdjustmentsarray of RegionalAdjustmentAddКорректировки по региону показа.
VideoAdjustmentVideoAdjustmentAddКорректировка по видео.
Структура MobileAdjustmentAdd
BidModifierint

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

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

Да
Структура DemographicsAdjustmentAdd
GenderGenderEnum

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

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

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

Возрастная группа пользователя: одно из значений 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.
BidModifierint

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

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

Да
Структура RetargetingAdjustmentAdd
RetargetingConditionIdlongИдентификатор условия ретаргетинга и подбора аудитории. См. раздел Условие ретаргетинга и подбора аудитории (RetargetingList).Да
BidModifierint

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

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

Да
Структура RegionalAdjustmentAdd
RegionIdlong

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

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

Да
BidModifierint

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

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

Да
Структура VideoAdjustmentAdd
BidModifierint

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

Указывается в процентах от 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)
AddResultsarray of MultiIdsActionResultРезультаты добавления корректировок.
Структура MultiIdsActionResult
Idsarray of longИдентификаторы созданных корректировок. Возвращаются в случае отсутствия ошибок, см. раздел Операции над массивом объектов. Следуют в том же порядке, что и корректировки в запросе.
Warningsarray of ExceptionNotification

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

Errorsarray 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 ]
      }
    ]
  }
}