add
Создает корректировки ставок.
Ограничения
Не более 1 корректировки ставок на мобильных для одной кампании или группы объявлений.
Не более 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 | Значение коэффициента к ставке для показа объявлений на мобильных телефонах. Указывается в процентах:
| Да |
OperatingSystemType | OperatingSystemTypeEnum | Тип операционной системы. Если параметр не указан, подразумевается любая операционная система. | Нет |
Структура TabletAdjustmentAdd | |||
BidModifier | int | Значение коэффициента к ставке для показа объявлений на планшетах. Указывается в процентах:
| Да |
OperatingSystemType | OperatingSystemTypeEnum | Тип операционной системы. Если параметр не указан, подразумевается любая операционная система. | Нет |
Структура DesktopAdjustmentAdd | |||
BidModifier | int | Значение коэффициента к ставке для показа объявлений на компьютерах, Smart TV. Указывается в процентах:
Ставка умножается на значение BidModifier/100. В одной группе объявлений коэффициент для показа на мобильных без указания операционной системы и коэффициент для показа на компьютерах, планшетах, Smart TV не допускается устанавливать одновременно равными 0. | Да |
Структура DesktopOnlyAdjustmentAdd | |||
BidModifier | int | Значение коэффициента к ставке для показа объявлений только на компьютерах. Указывается в процентах:
Ставка умножается на значение 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 | Блок показа объявления:
| Да |
BidModifier | int | Значение коэффициента к ставке для показа объявлений в указанной позиции. Указывается в процентах от 1 до 1300. Ставка умножается на значение BidModifier/100. | Да |
Структура IncomeGradeAdjustmentAdd | |||
Grade | IncomeGradeEnum | Уровень платежеспособности:
| Да |
BidModifier | int | Значение коэффициента к ставке для показа объявлений пользователям с определенным уровнем платежеспособности. Указывается в процентах от 1 до 1300. Ставка умножается на значение BidModifier/100. | Да |
Структура AdGroupAdjustmentAdd | |||
BidModifier | int | Значение коэффициента к ставке для показа объявлений из определенной группы. Указывается в процентах от 1 до 1300. Ставка умножается на значение BidModifier/100. | Да |
Параметр | Тип | Описание | Обязательный |
Структура 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 | Значение коэффициента к ставке для показа объявлений на мобильных телефонах. Указывается в процентах:
| Да |
OperatingSystemType | OperatingSystemTypeEnum | Тип операционной системы. Если параметр не указан, подразумевается любая операционная система. | Нет |
Структура TabletAdjustmentAdd | |||
BidModifier | int | Значение коэффициента к ставке для показа объявлений на планшетах. Указывается в процентах:
| Да |
OperatingSystemType | OperatingSystemTypeEnum | Тип операционной системы. Если параметр не указан, подразумевается любая операционная система. | Нет |
Структура DesktopAdjustmentAdd | |||
BidModifier | int | Значение коэффициента к ставке для показа объявлений на компьютерах, Smart TV. Указывается в процентах:
Ставка умножается на значение BidModifier/100. В одной группе объявлений коэффициент для показа на мобильных без указания операционной системы и коэффициент для показа на компьютерах, планшетах, Smart TV не допускается устанавливать одновременно равными 0. | Да |
Структура DesktopOnlyAdjustmentAdd | |||
BidModifier | int | Значение коэффициента к ставке для показа объявлений только на компьютерах. Указывается в процентах:
Ставка умножается на значение 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 | Блок показа объявления:
| Да |
BidModifier | int | Значение коэффициента к ставке для показа объявлений в указанной позиции. Указывается в процентах от 1 до 1300. Ставка умножается на значение BidModifier/100. | Да |
Структура IncomeGradeAdjustmentAdd | |||
Grade | IncomeGradeEnum | Уровень платежеспособности:
| Да |
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 | Ошибки, возникшие при выполнении операции. |
Параметр | Тип | Описание |
Структура 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 ] } ] } }