Google Ads

Matching Functions  |  AdWords API  |  Google Developers

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:

For example, a
Function
that selects
FeedItem objects
with
feedItemId of
1000001, 1000002, or 1000003 has the following attributes:

  1. lhsOperand =RequestContextOperand
    with
    contextType= FEED_ITEM_ID
  2. operator = IN
  3. 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:

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:

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

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button
Close