add
Creates dynamic text ad targets and sets bids or priorities for the created targets.
The bid or priority is used depending on which display strategy is selected in the campaign:
If the campaign has an automatic strategy set up, the StrategyPriority parameter is used: ads for dynamic text ad targets with higher priority are allocated more traffic when possible, and they are the last ones to be stopped when budget funds are low.
If a manual strategy is set up in the campaign, the Bid parameter is used.
The ContextBid parameter is not used at this time.
If an item in the input array contains parameters that are not appropriate for the strategy, the values of these parameters are saved and a warning is issued.
If an automatic strategy is set up in the campaign, but the Bid parameter is set for a dynamic text ad target, this bid value won't be applied. When the strategy switches from automatic to manual, the bid will be selected by an automatic algorithm.
If a manual strategy is set up in the campaign, but the StrategyPriority parameter is set for a dynamic text ad target, the set priority value will be applied later when the strategy is switched to an automatic one.
If the strategy allows for setting bids but the bid is not specified, the minimum bid is set by default (the minimum bid depends on the advertiser's currency). If the strategy allows for setting priority but the priority is not specified, the average priority is set by default.
Bids and prices are passed via the Yandex Direct API as integers. The value passed is a bid or price multiplied by 1,000,000.
All bids and prices are shown in the advertiser's currency.
Restrictions
Dynamic text ad targets can only be added to a DYNAMIC_TEXT_AD_GROUP type of ad group.
Maximum of 50 dynamic text ad targets per ad group.
Maximum of 1000 dynamic text ad targets per method call.
Request
Request structure in JSON format:
{
"method": "add",
"params": { /* params */
"Webpages": [{ /* WebpageAddItem */
"Name": (string), /* required */
"AdGroupId": (long), /* required */
"Conditions": [{ /* WebpageCondition */
"Operand": ( "DOMAIN" | "OFFERS_LIST_URL" | "PAGE_CONTENT" | "PAGE_TITLE" | "URL" ), /* required */
"Operator": ( "EQUALS_ANY" | "NOT_EQUALS_ALL" | "CONTAINS_ANY" | "NOT_CONTAINS_ALL" ), /* required */
"Arguments": [(string), ... ] /* required */
}, ... ],
"Bid": (long),
"ContextBid": (long),
"StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" )
}, ... ] /* required */
}
}
Parameter | Type | Description | Required |
Params structure (for JSON) / AddRequest structure (for SOAP) | |||
---|---|---|---|
Webpages | array of WebpageAddItem | The dynamic text ad targets to add. | Yes |
WebpageAddItem structure | |||
Name | string | Name of a dynamic text ad target (maximum of 100 characters). | Yes |
AdGroupId | long | ID of the group to add the dynamic text ad target to. | Yes |
Conditions | array of WebpageCondition | Rules for page filtering. Maximum of 10 items in the array. A dynamic ad is generated if the page meets all the selection rules at the same time. If this parameter is omitted, a dynamic text ad target is created with the PAGES_ALL type (“All website pages”). | No |
Bid | long | The bid on search, multiplied by 1,000,000. Integer. Only used for a manual strategy. Specified in the advertiser's currency. Restrictions are listed in the currency reference. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request. | No |
ContextBid | long | This parameter is reserved for future use. | No |
StrategyPriority | PriorityEnum | The priority of the dynamic text ad target: LOW, NORMAL or HIGH. Only used for an automatic strategy. | No |
WebpageCondition structure | |||
Operand | WebpageCondition OperandEnum | The operand is a property of a site page to compare with the argument. For a description of the operands, see Selection rule. | Yes |
Operator | StringCondition OperatorEnum | How the operand and argument are compared. For a description of the operators, see Selection rule. | Yes |
Arguments | array of string | An array of strings to compare the operand to. Maximum of 10 strings in the array. If the operand is OFFERS_LIST_URL, the length of each string must be less than 1024 characters. In all other cases, each string can have a maximum of 100 characters. | Yes |
Parameter | Type | Description | Required |
Params structure (for JSON) / AddRequest structure (for SOAP) | |||
---|---|---|---|
Webpages | array of WebpageAddItem | The dynamic text ad targets to add. | Yes |
WebpageAddItem structure | |||
Name | string | Name of a dynamic text ad target (maximum of 100 characters). | Yes |
AdGroupId | long | ID of the group to add the dynamic text ad target to. | Yes |
Conditions | array of WebpageCondition | Rules for page filtering. Maximum of 10 items in the array. A dynamic ad is generated if the page meets all the selection rules at the same time. If this parameter is omitted, a dynamic text ad target is created with the PAGES_ALL type (“All website pages”). | No |
Bid | long | The bid on search, multiplied by 1,000,000. Integer. Only used for a manual strategy. Specified in the advertiser's currency. Restrictions are listed in the currency reference. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request. | No |
ContextBid | long | This parameter is reserved for future use. | No |
StrategyPriority | PriorityEnum | The priority of the dynamic text ad target: LOW, NORMAL or HIGH. Only used for an automatic strategy. | No |
WebpageCondition structure | |||
Operand | WebpageCondition OperandEnum | The operand is a property of a site page to compare with the argument. For a description of the operands, see Selection rule. | Yes |
Operator | StringCondition OperatorEnum | How the operand and argument are compared. For a description of the operators, see Selection rule. | Yes |
Arguments | array of string | An array of strings to compare the operand to. Maximum of 10 strings in the array. If the operand is OFFERS_LIST_URL, the length of each string must be less than 1024 characters. In all other cases, each string can have a maximum of 100 characters. | Yes |
Response
Response structure in JSON format:
{
"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)
}, ... ]
}, ... ]
}
}
Parameter | Type | Description |
Result structure (for JSON) / AddResponse structure (for SOAP) | ||
---|---|---|
AddResults | array of ActionResult | Results of adding dynamic text ad targets. |
ActionResult structure | ||
Id | long | ID of the created dynamic text ad target. Returned if there aren't any errors. See the section Operations on object arrays. |
Warnings | array of ExceptionNotification | Warnings that occurred during the operation. |
Errors | array of ExceptionNotification | Errors that occurred during the operation. |
Parameter | Type | Description |
Result structure (for JSON) / AddResponse structure (for SOAP) | ||
---|---|---|
AddResults | array of ActionResult | Results of adding dynamic text ad targets. |
ActionResult structure | ||
Id | long | ID of the created dynamic text ad target. Returned if there aren't any errors. See the section Operations on object arrays. |
Warnings | array of ExceptionNotification | Warnings that occurred during the operation. |
Errors | array of ExceptionNotification | Errors that occurred during the operation. |
Example
Selection of tablet pages for creating ads of tablets that are represented in the list of tablets, excluding those that are sold out and out of stock.
{
"method" : "add",
"params": {
"Webpages":[
{
"AdGroupId":831821811,
"Name":"Tablets",
"Bid":800000,
"Conditions": [
{
"Operand":"PAGE_CONTENT",
"Operator":"NOT_CONTAINS_ALL",
"Arguments":["Item out of stock"]
},
{
"Operand":"PAGE_CONTENT",
"Operator":"NOT_CONTAINS_ALL",
"Arguments": ["Item sold out"]
},
{
"Operand":"OFFERS_LIST_URL",
"Operator":"EQUALS_ANY",
"Arguments":["http://example.com/tablets/tablets-195"]
}
]
}
]
}
}