Matching Functions

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 with contextType= 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 Name	Attribute 1 Line 2	Attribute 2 Line 3	Attribute 3 Final URLs
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 must be exactly 1 `ConstantOperand` for `EQUALS` max of 20 `ConstantOperands` for `IN`
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 must be exactly one `ConstantOperand` for `EQUALS` maximum of three `ConstantOperands` for `CONTAINS_ANY`
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 20 ConstantOperand objects.
EQUALS operator: The rhsOperand must contain exactly 1 ConstantOperand object.
AND operator: The lhsOperand must contain at least 2 FunctionOperand objects. The rhsOperand should not be set.
CONTAINS_ANY operator: The rhsOperand must contain at least 1 and no more than 3 ConstantOperand objects.
IDENTITY operator: The lhsOperand must contain exactly 1 ConstantOperand with its booleanValue set. The rhsOperand 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 to true 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.

Next steps

Create sitelinks using feed services
Create location extensions
Check out the list of available placeholder types and fields