add

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

Узнайте больше

Ограничения

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

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

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

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

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

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

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

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

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

Запрос

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

{
  "method": "add",
  "params": { /* params */
    "BidModifiers": [{  /* BidModifierAddItem */
      "MobileAdjustment": {  /* MobileAdjustmentAdd */
        "BidModifier": (int), /* required */
        "OperatingSystemType": ( "IOS" | "ANDROID" )
      },
      "TabletAdjustment": {  /* MobileAdjustmentAdd */
        "BidModifier": (int), /* required */
        "OperatingSystemType": ( "IOS" | "ANDROID" )
      },
      "DesktopAdjustment": {  /* DesktopAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "DesktopOnlyAdjustment": {  /* 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 */
      },
      "SmartAdAdjustment" : { /* SmartAdAdjustmentAdd */
        "BidModifier": (int) /* required */
      },
      "SerpLayoutAdjustments": [{  /* SerpLayoutAdjustmentAdd */
        "SerpLayout": ( "ALONE" | "SUGGEST" ), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "IncomeGradeAdjustments": [{  /* IncomeGradeAdjustmentAdd */
        "Grade": ( "VERY_HIGH" | "HIGH" | "ABOVE_AVERAGE" ), /* required */
        "BidModifier": (int) /* required */
      }, ... ],
      "AdGroupAdjustment" : {
        "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, либо TabletAdjustment, либо DesktopAdjustment, либо DesktopOnlyAdjustment, либо DemographicsAdjustments, либо RetargetingAdjustments, либо RegionalAdjustments, либо VideoAdjustment, либо SmartAdAdjustment, либо SerpLayoutAdjustments либо IncomeGradeAdjustments либо AdGroupAdjustment.

TabletAdjustment

TabletAdjustmentAdd

Корректировка на планшетах.

DesktopAdjustment

DesktopAdjustmentAdd

Корректировка на компьютерах, Smart TV.

DesktopOnlyAdjustment

DesktopOnlyAdjustmentAdd

Корректировка только на компьютерах.

DemographicsAdjustments

array of DemographicsAdjustmentAdd

Корректировки по полу и возрасту. Не более 12 элементов в массиве.

RetargetingAdjustments

array of RetargetingAdjustmentAdd

Корректировки для целевой аудитории. Не более 100 элементов в массиве.

RegionalAdjustments

array of RegionalAdjustmentAdd

Корректировки по региону показа.

VideoAdjustment

VideoAdjustmentAdd

Корректировка для видеодополнений.

SmartAdAdjustment

SmartAdAdjustmentAdd

Корректировка для смарт-объявлений.

SerpLayoutAdjustments

array of SerpLayoutAdjustmentAdd

Корректировки на эксклюзивное размещение.

IncomeGradeAdjustments

array of IncomeGradeAdjustmentAdd

Корректировки на платежеспособность.

AdGroupAdjustment

array of AdGroupAdjustmentAdd

Корректировки на группу.

Структура MobileAdjustmentAdd

BidModifier

int

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

Указывается в процентах:

  • От 0 до 1300 — для корректировок во всех типах кампаний и групп.

Ставка умножается на значение BidModifier/100.

Да

OperatingSystemType

OperatingSystemTypeEnum

Тип операционной системы.

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

Нет

Структура TabletAdjustmentAdd

BidModifier

int

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

Указывается в процентах:

  • От 0 до 1300 — для корректировок во всех типах кампаний и групп.

Ставка умножается на значение BidModifier/100.

Да

OperatingSystemType

OperatingSystemTypeEnum

Тип операционной системы.

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

Нет

Структура DesktopAdjustmentAdd

BidModifier

int

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

Указывается в процентах:

  • От 0 до 1300 — для корректировок во всех типах кампаний и групп.

Ставка умножается на значение BidModifier/100.

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

Да

Структура DesktopOnlyAdjustmentAdd

BidModifier

int

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

Указывается в процентах:

  • От 0 до 1300 — для корректировок во всех типах кампаний и групп.

Ставка умножается на значение BidModifier/100.

В одной группе объявлений коэффициент для показа на мобильных без указания операционной системы и коэффициент для показа только на компьютерах не допускается устанавливать одновременно равными 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.

Да

Структура SmartAdAdjustmentAdd

BidModifier

int

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

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

Да

Структура SerpLayoutAdjustmentAdd

SerpLayout

SerpLayoutEnum

Блок показа объявления:

  • ALONE — Эксклюзивное размещение.
  • SUGGEST — Реклама в саджесте.

Да

BidModifier

int

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

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

Да

Структура IncomeGradeAdjustmentAdd

Grade

IncomeGradeEnum

Уровень платежеспособности:

  • VERY_HIGH
  • HIGH
  • ABOVE_AVERAGE

Да

BidModifier

int

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

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

Да

Структура AdGroupAdjustmentAdd

BidModifier

int

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

Указывается в процентах от 1 до 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 ]
          }
        ]
      }
    }
Предыдущая
BidModifiers: управление корректировками ставок
Следующая
delete