This article refers to the old scripts based Bid Rule Engine
The Bid Rule Engine supports advanced conditions and can set bids based on complex formulas that you write. While you can create the most commonly used rules using easy-to-use form fields, more complex rules may require that you write the rules yourself using a special syntax. The following guide explains how this syntax works so that you can use the full potential of our Bid Rule Engine.
There are several places where you can add advanced syntax to the Bid Rule Engine:
To enter advanced syntax in the condition field, you first have to click the "Advanced" button next to the condition you'd like to update.
AdWords entities like campaigns, ad groups, and keywords have attributes and metrics. Attributes are things that have only a current value that does not depend on the date range you are looking at. For example, Quality Score (QS) is an attribute of a keyword that tells you the current QS of that keyword. You can access several attributes of ad groups and keywords through the Bid Rule Engine's advanced syntax.
adgroup.CpcBid keyword.KeywordText keyword.KeywordMatchType keyword.FirstPageCpc keyword.TopOfPageCpc keyword.QualityScore
Unlike attributes which have a static value that does not depend on the date range evaluated, metrics depend on the time frame you are looking at. For example, the average CPC of a keyword today may differ from its average CPC yesterday. Because there is a time element, the syntax includes a place to specify the time frame.
account['last 30 days']['ConversionValue'] campaign['last 30 days']['Conversions'] adgroup['last 14 days']['Cost'] keyword['last 14 days']['Clicks']
You can use any lookback window you wish for the Bid Rule Engine. We have added several common date ranges by default but these can be edited, and new ones can be added in the "Advanced Settings". Because you can name the date ranges any way you want, there is no set syntax for calling date ranges in the rules. You simply use the exact same names and capitalization as in the date range settings.
It is possible in AdWords to get conversion data for a specific type of conversion. We have a special syntax that allows you to get the right type of conversion data.
entityName['date range'].conversionStats['Conversion Type'].MetricName
Accepted values for conversion type:
Available conversion metrics when segmenting by type:
campaign['last 30 days'].conversionStats['Other'].Conversions campaign['last 30 days'].conversionStats['Signup'].Conversions adgroup['last 14 days'].conversionStats['Lead'].Conversions adgroup['last 14 days'].conversionStats['View of a key page'].Conversions keyword['last 240 days']conversionStats['View of a key page'].ConvertedClicks keyword['last 240 days']conversionStats['Purchase/Sale'].ConvertedClicks
It is possible in AdWords to get conversion data for each conversion you have defined. Here's how to use metrics for a specific AdWords conversion in the Bid Rule engine.
entityName['date range'].conversionStats['Conversion Name'].MetricName
Replace 'Conversion Name' with the name you are using in AdWords. These names are set by the advertiser so check the Conversions page in AdWords to find the names you can use. Here's an example:
Available conversion metrics when segmenting by type:
campaign['last 30 days'].conversionStats['Contact Us (All Web Site Data)'].Conversions campaign['last 30 days'].conversionStats['Paid Signup'].Conversions adgroup['last 14 days'].conversionStats['Paid Signup'].Conversions adgroup['last 14 days'].conversionStats['Trial Signup'].Conversions keyword['last 240 days']conversionStats['Contact Us (All Web Site Data)'].ConvertedClicks keyword['last 240 days']conversionStats['Trial Signup'].ConvertedClicks
The Bid Rule Engine can use data you maintain on a Google Spreadsheet as part of the advanced syntax. This makes it possible to add any type of numerical data you want to use as part of bid rules without having to import that data into AdWords first.
entityName.myMetrics["Name of custom metric"]
The data from the external sheet is associated with the most specific entity you have defined on the associated row. You define which entity gets the data by filling in either campaign name, campaign name + ad group name, or campaign name + ad group name + keyword text + keyword match type. You can mix and match the entities on the spreadsheet, i.e. you can include some rows with data for campaigns, some with data for ad groups, and some with data for keywords.
Consider the following example spreadsheet where we have added 2 custom metrics that we want to use with the Bid Rule Engine: 'CPA target' and 'My Own Metric'.
Each line fully defines a keyword so the custom metrics are only available at the keyword level and the syntax is as follows:
keyword.myMetrics["CPA Target"] keyword.myMetrics["My Own Metric"]
Using the same data as in example 1, we now identify data for a keyword, then an ad group, and then a campaign by leaving some of the fields on the spreadsheet blank:
Here are the 6 pieces of data we could now access from this spreadsheet:
keyword.myMetrics["CPA Target"] - the value is 10 keyword.myMetrics["My Own Metric"] - the value is 0.7 adgroup.myMetrics["CPA Target"] - 12 adgroup.myMetrics["My Own Metric"] - 1.1 campaign.myMetrics["CPA Target"] - 10 campaign.myMetrics["My Own Metric"] - 0.85
As of March 2016, we added support for account-level data to be added to the external spreadsheet. To do this, simply leave the fields for campaign, ad group, and keyword blank. Whatever data appears in that row will be associated with the account.
Here are some examples of how to call account-level data in the settings of the Bid Rule Engine:
account.myMetrics["target CPC"] - the value is 1 account.myMetrics["second metric"] - the value is 5 account.myMetrics["some string"] - the value is 'alpha'
The real power of the advanced syntax lies in the fact that you can use it to write your own formulasfor the condition, new bid, minimum bid, and maximum bid.
If you want to calculate max CPC from conversion rate and a target CPA maintained in an external spreadsheet, you could use the following syntax:
adgroup.myMetrics["CPA target"] * adgroup['last 14 days'].conversionStats['Lead'].Conversions / adgroup['last 14 days'].Clicks
Let's break this formula down into its components:
Here is a roundup of the accepted values for each of the elements of the advanced syntax.
Use any date range that you have created in advanced settings, using the exact name with the same capitalization. Here are the defaults assuming you have not made any changes to the date ranges in your settings:
The following operators are supported:
Most metrics from the AdWords reporting API are supported. See specific details of the available metrics further below. Note that capitalization matters and that not every entity can access every metric due to limitations in AdWords reporting.
Here are some examples of how to use this:
keyword.KeywordMatchType == "Broad" keyword.KeywordMatchType != "Exact"
Note that Modified Broad Match is not technically a match type in AdWords, rather it is a broad match keyword with special notation. As a result this tool also doesn't have a classification for modified broad match.
Our award-winning customer care team is here for you.