How to write advanced bid management rules

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.


Where to enter advanced conditions and calculations

There are several places where you can add advanced syntax to the Bid Rule Engine:

  1. In the condition field of a rule
  2. In the action field of a rule
  3. In the minimum and maximum bid fields of a rule

Where to use advanced syntax

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 Attributes

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.

Basic Structure

entityName.AttributeName

Examples

adgroup.CpcBid
keyword.KeywordText
keyword.KeywordMatchType
keyword.FirstPageCpc
keyword.TopOfPageCpc
keyword.QualityScore

AdWords Metrics

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.

Basic Structure

entityName['date range']['MetricName']

Examples

account['last 30 days']['ConversionValue']
campaign['last 30 days']['Conversions']
adgroup['last 14 days']['Cost']
keyword['last 14 days']['Clicks']

Date Ranges

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.

Here are the default date ranges for the Bid Rule Engine:

Custom Date Ranges

Examples:

Here is the syntax that corresponds to the date ranges you see above.

keyword['Today']['Clicks']
keyword['Yesterday']['Clicks']
keyword['last 7 days']['Clicks']
keyword['last 14 days']['Clicks']
keyword['last 30 days']['Clicks']
keyword['last 60 days']['Clicks']
keyword['last 14 days']['Clicks']

AdWords Metrics by Conversion Type

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. 

Basic Syntax

entityName['date range'].conversionStats['Conversion Type'].MetricName

Accepted values for conversion type:

  • Other
  • View of a key page
  • Purchase/Sale
  • Signup
  • Lead

Available conversion metrics when segmenting by type:

  • AllConversions
  • Conversions
  • ConvertedClicks
  • ConversionValue
  • ConversionCategoryName
  • ConversionTypeName


Examples

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

AdWords Metrics by Conversion Name

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. 

Basic Syntax

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:

  • AllConversions
  • Conversions
  • ConvertedClicks
  • ConversionValue
  • ConversionCategoryName
  • ConversionTypeName


Examples (using the names from the screenshot above)

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

Data From External Sheet

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.

Basic Syntax

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.

Example 1

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'.

Image title

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"]

Example 2

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:

Image title

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

Example 3

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.

Image title

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'

Creating Formulas

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.

Basic Syntax

  • When writing a formula you MUST include a space before any operator (e.g. *, +, -, /).
  • You can use any operator.
  • You can use parentheses to specify in what order a formula is calculated.

Example

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:

  • adgroup.myMetrics["CPA target"] - This is ad group level data from an externally maintained spreadsheet where 1 of the column headers is "CPA target". All ad groups for which bids are going to be calculated must have a value for the field "CPA target", otherwise the Bid Rule Engine will fail to calculate new bids.
  • adgroup['last 14 days'].conversionStats['Lead'].Conversions - This is the ad group's number of conversions for the past 14 days where the conversion type was "Lead".
  • adgroup['last 14 days'].Clicks - This is the number of clicks the ad group received over the past 14 days.

Accepted Values

Here is a roundup of the accepted values for each of the elements of the advanced syntax.

Entities

  • Account
  • Campaign
  • Ad group
  • Keyword

Date Ranges

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:

  • Today
  • Yesterday
  • last 7 days
  • last 14 days
  • last 30 days
  • last 60 days
  • last 90 days
  • last 120 days
  • last 180 days
  • last 240 days

Operators

The following operators are supported:

  • >=
  • >
  • <=
  • <
  • ==
  • !=

Metric and Attribute Names and Data Types

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. 

Account Metrics 

  • AllConversions
  • AllConversionValue
  • AllConversionRate
  • AverageCpc
  • Ctr
  • Impressions
  • Clicks
  • AveragePosition
  • Cost
  • ConversionRate
  • Conversions
  • ConversionValue
  • ConvertedClicks
  • CostPerConversion
  • CostPerAllConversion
  • CrossDeviceConversions
  • SearchExactMatchImpressionShare
  • SearchImpressionShare
  • SearchRankLostImpressionShare
  • ValuePerConversion
  • ValuePerAllConversion
  • ViewThroughConversions

Campaign Attributes

  • CampaignName
  • CampaignId

Campaign Metrics

  • AllConversionRate
  • AllConversions
  • AllConversionValue
  • AverageCpc
  • AveragePageviews
  • AveragePosition
  • AverageTimeOnSite
  • BounceRate
  • ClickAssistedConversions
  • ClickAssistedConversionsOverLastClickConversions
  • ClickAssistedConversionValue
  • ClickConversionRate
  • Clicks
  • ContentBudgetLostImpressionShare
  • ContentImpressionShare
  • ContentRankLostImpressionShare
  • ConversionRate
  • Conversions
  • ConversionValue
  • ConvertedClicks
  • Cost
  • CostPerAllConversion
  • CostPerConversion
  • CostPerConvertedClick
  • CrossDeviceConversions
  • Ctr
  • ImpressionAssistedConversions
  • ImpressionAssistedConversionValue
  • Impressions
  • PercentNewVisitors
  • SearchBudgetLostImpressionShare
  • SearchExactMatchImpressionShare
  • SearchExactMatchImpressionShare
  • SearchImpressionShare
  • SearchRankLostImpressionShare
  • ValuePerAllConversion
  • ValuePerConversion
  • ValuePerConvertedClick
  • ViewThroughConversions

Ad Group Attributes

  • AdGroupId
  • AdGroupName
  • CampaignId
  • CampaignName
  • CpcBid

Ad Group Metrics

  • AllConversionRate
  • AllConversions
  • AllConversionValue
  • AverageCpc
  • AveragePageviews
  • AveragePosition
  • AverageTimeOnSite
  • BounceRate
  • ClickAssistedConversions
  • ClickAssistedConversionsOverLastClickConversions
  • ClickAssistedConversionValue
  • ClickConversionRate
  • Clicks
  • ContentImpressionShare
  • ConversionRate
  • Conversions
  • ConversionValue
  • ConvertedClicks
  • Cost
  • CostPerAllConversion
  • CostPerConversion
  • CostPerConvertedClick
  • CrossDeviceConversions
  • Ctr
  • ImpressionAssistedConversions
  • ImpressionAssistedConversionValue
  • Impressions
  • PercentNewVisitors
  • SearchExactMatchImpressionShare
  • SearchExactMatchImpressionShare
  • SearchImpressionShare
  • SearchRankLostImpressionShare
  • ValuePerAllConversion
  • ValuePerConversion
  • ValuePerConvertedClick
  • ViewThroughConversions

Keyword Attributes

  • AdGroupId
  • AdGroupName
  • CampaignId
  • CampaignName
  • CpcBid
  • Criteria
  • FirstPageCpc
  • Id
  • KeywordMatchType
  • QualityScore
  • TopOfPageCpc

Keyword Metrics

  • AllConversionRate
  • AllConversions
  • AllConversionValue
  • AverageCpc
  • AveragePageviews
  • AveragePosition
  • AverageTimeOnSite
  • BounceRate
  • ClickAssistedConversions
  • ClickAssistedConversionsOverLastClickConversions
  • ClickAssistedConversionValue
  • ClickConversionRate
  • Clicks
  • ConversionRate
  • Conversions
  • ConversionValue
  • ConvertedClicks
  • Cost
  • CostPerAllConversion
  • CostPerConversion
  • CostPerConvertedClick
  • CrossDeviceConversions
  • Ctr
  • ImpressionAssistedConversions
  • ImpressionAssistedConversionValue
  • Impressions
  • PercentNewVisitors
  • SearchExactMatchImpressionShare
  • SearchExactMatchImpressionShare
  • SearchImpressionShare
  • SearchRankLostImpressionShare
  • ValuePerAllConversion
  • ValuePerConversion
  • ValuePerConversionManyPerClick
  • ValuePerConvertedClick
  • ViewThroughConversions

Conversion Metrics For Specific Conversion Types

  • AllConversionRate
  • AllConversions
  • ConversionCategoryName
  • ConversionRate
  • Conversions
  • ConversionValue
  • ConvertedClicks

Attribute Values

KeywordMatchType

  • Broad
  • Phrase
  • Exact

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.


Can’t find what you’re looking for?

Our award-winning customer care team is here for you.