CustomerFeed
,
CampaignFeed
,
and
AdGroupFeed
objects in the AdWords API allow you to define selection criteria for feed items
via a matching function. A matching function consists of three fields:
Field | Type |
---|---|
lhsOperand |
FunctionArgumentOperand |
operator |
Function.Operator |
rhsOperand |
FunctionArgumentOperand |
For example, a
Function
that selects
FeedItem
objects
with
feedItemId
of
1000001, 1000002, or 1000003 has the following attributes:
lhsOperand =
RequestContextOperand
withcontextType
= FEED_ITEM_ID
operator = IN
rhsOperand = [1000001, 1000002, 1000003]
As an alternative to creating operand and operator objects, you can set the
function's
functionString
to create an equivalent function:
IN(FEED_ITEM_ID,{1000001,1000002,1000003})
In addition to simple functions, you can combine multiple functions to create a new function, with some restrictions (more on that later in this guide).
The sections below discuss the rules AdWords API uses to validate matching functions.
Example feed items
The example uses the following feed items from a fictional feed ID 12345678.
FeedItem ID | Attribute 0 |
Attribute 1 |
Attribute 2 |
Attribute 3 |
---|---|---|---|---|
1000001 | Mars cruise | Travel at light speed | 140 million miles | [http://www.example.com/mars] |
1000002 | Venus cruise | Travel at light speed | 162 million miles | [http://www.example.com/venus] |
1000003 | Jupiter cruise | Lunch included | 365 million miles | [http://www.example.com/jupiter1, http://www.example.com/jupiter2] |
1000004 | Moon cruise | Free pretzels | 238,900 miles | [http://www.example.com/moon] |
Function types
The API supports the following leaf node function types. Functions composed of other functions are covered in the next section.
Selection by platform (mobile or desktop)
This function type lets you limit display of specific ad extensions (placeholder types) to mobile or desktop users.
Field | Valid Value |
---|---|
lhsOperand |
RequestContextOperand with contextType = DEVICE_PLATFORM |
operator |
EQUALS |
rhsOperand |
a single ConstantOperand of either Mobile or Desktop (case-sensitive) |
Function string example | |
EQUALS(CONTEXT.DEVICE,"Mobile") |
Selection by feed item ID
This function type lets you select feed items by specifying their
feedItemId
.
The function string below will select the first three feed items (Mars cruise, Venus cruise, and Jupiter cruise) by their feed item IDs.
Field | Valid Value |
---|---|
lhsOperand |
RequestContextOperand with contextType = FEED_ITEM_ID |
operator |
EQUALS or IN |
rhsOperand |
one or more ConstantOperands
|
Function string example | |
IN(FEED_ITEM_ID,{1000001,1000002,1000003}) |
Selection by feed attribute
This function type lets you select feed items based on the value of a specific
attribute of a FeedItem
.
The function string below will select the first, second, and fourth feed items by their values for attribute 0.
Field | Valid Value |
---|---|
lhsOperand |
FeedAttributeOperand with
feedId
and
feedAttributeId
set
|
operator |
EQUALS or CONTAINS_ANY |
rhsOperand |
one or more ConstantOperands
|
Function string example | |
CONTAINS_ANY(FeedAttribute[12345678,0],{"Mars cruise","Venus cruise","Moon cruise"})
|
Identity functions (always true or always false)
This function lets you define a condition that always evaluates to true or
false. You can use a function string of IDENTITY(true)
to
select all of the feed items in a feed.
The function string example below selects none of the feed items in the feed. Use this type of function to disable ad extensions of a specific type at the customer, campaign, or ad group level.
Field | Value |
---|---|
lhsOperand |
exactly one ConstantOperand with its booleanValue
set to true or false
|
operator |
IDENTITY |
rhsOperand |
none |
Function string example | |
IDENTITY(false) |
Combining functions
You can use
FunctionOperand
with the AND
operator to logically combine two or more functions to form a
new matching function.
The function string example below will select the first three feed items by feed item ID, but only if the impression is for a mobile device.
Field | Valid Value |
---|---|
lhsOperand |
At least two FunctionArgumentOperand objects |
operator |
AND |
rhsOperand |
none |
Function string example | |
AND(IN(FEED_ITEM_ID,{1000001,1000002,1000003}),EQUALS(CONTEXT.DEVICE,"Mobile"))
|
When combining functions, the lhsOperand
can only consist of:
Either:
- One or more feed item ID functions OR
- One or more feed attribute functions
AND (optional) at most one platform function
In addition, you can only use a FunctionOperand
in a top level Function
. You
cannot nest FunctionOperand
objects.
Here are some examples of valid and invalid function strings:
Function string | Valid | Notes |
---|---|---|
AND( IN(FEED_ITEM_ID,{1000001,1000002, 1000003}), EQUALS(CONTEXT.DEVICE,"Mobile")) |
Yes | Valid - consists of a feed item ID function and a platform function |
AND( CONTAINS_ANY(FeedAttribute[12345678,0], {"Mars cruise","Venus cruise", "Moon cruise"}), EQUALS(CONTEXT.DEVICE,"Mobile")) |
Yes | Valid - consists of a feed attribute function and a platform function |
AND( CONTAINS_ANY(FeedAttribute[12345678,0], {"Mars cruise","Venus cruise", "Moon cruise"}), CONTAINS_ANY(FeedAttribute[12345678,2], { "140 million miles", "162 million miles"})) |
Yes | Valid - consists of two feed attribute functions |
AND( IN(FEED_ITEM_ID,{1000001,1000002, 1000003}), CONTAINS_ANY(FeedAttribute[12345678,0], {"Mars cruise","Venus cruise", "Moon cruise"})) |
No | Invalid - cannot combine feed item ID functions and feed attribute functions |
AND( AND( IN(FEED_ITEM_ID, {1000001,1000002,1000003}), EQUALS(CONTEXT.DEVICE,"Mobile")), AND( CONTAINS_ANY( FeedAttribute[12345678,0], {"Mars cruise","Venus cruise", "Moon cruise"}), CONTAINS_ANY(FeedAttribute[ 12345678,1], {"Free pretzels","Lunch included"}) ) ) |
No | Invalid - cannot nest combining functions |
Function operator rules
Below are the validation rules for each function
Operator
.
IN
operator- The
rhsOperand
must contain at least 1 and no more than 20ConstantOperand
objects. EQUALS
operator- The
rhsOperand
must contain exactly 1ConstantOperand
object. AND
operator- The
lhsOperand
must contain at least 2FunctionOperand
objects. TherhsOperand
should not be set. CONTAINS_ANY
operator- The
rhsOperand
must contain at least 1 and no more than 3ConstantOperand
objects. IDENTITY
operator- The
lhsOperand
must contain exactly 1ConstantOperand
with itsbooleanValue
set. TherhsOperand
should not be set.
CustomerFeed function rules
CustomerFeed
supports any placeholder type except
Call or
Message extensions.
For a CustomerFeed
matching function, you can use any of the
function types or
function combinations unless the CustomerFeed
is for location extensions.
CustomerFeed for location extensions
A CustomerFeed
for the
location placeholder type
must be one of the following:
- An identity function with
the
ConstantOperand.booleanValue
set totrue
OR - A platform function
CampaignFeed and AdGroupFeed function rules
You can use all of the function types and
function combinations above when constructing matching
functions for CampaignFeed
and AdGroupFeed
objects.
FeedItem targeting options
In addition to specifying a matching function at the customer, campaign, or ad
group level, you can also set targeting options on individual feed items by
setting the campaignTargeting
,
adGroupTargeting
,
or keywordTargeting
attributes.
These targeting options will be combined with the matching function to select which feed items will be used for a given impression.
For example, let's say you create a FeedItem
for sitelinks with the following
targeting options:
adGroupTargeting.TargetingAdGroupId = 12345
keywordTargeting.id = 7890
You then define an AdGroupFeed
for placeholder type 1 (sitelinks)
with a platform matching function
for Mobile
.
When serving impressions for this ad group, Google Ads will only serve sitelinks
from the FeedItem
if the impression attributes satisfy both the FeedItem
targeting options and the AdGroupFeed
matching function.
Example 1
Impression attributes: ad group ID 12345, keyword 7890, and a desktop user.
Result: The FeedItem
will not be used because the platform (desktop)
does not satisfy the AdGroupFeed
matching function.
Example 2
Impression attributes: ad group ID 12345, keyword 8910, and a mobile user.
Result: The FeedItem
will not be used because the keyword (7890) does
not satisfy the FeedItem
targeting options.
Example 3
Impression attributes: ad group ID 12345, keyword 7890, and a mobile user.
Result: The FeedItem
will be used because the attributes satisfy both
the AdGroupFeed
matching function and the FeedItem
targeting options.