This post explains how to use the AdWords API Conversion Import Tool to track your offline conversions. You store a click id that Google appends to your destination URLs then use it to upload the clicks once they convert offline. There's three steps you need to follow to get started using the tool:
- Create a new conversion type in AdWords for the upload.
- Collect the click ids and store them in your database.
- Upload each click that converts using the AdWords API.
I'll explain each step in the rest of the article.
Creating a New Conversion Type in AdWords
Before you can start importing conversions into AdWords, you need to create a new conversion type with a source of Import. You can create this using either the Tools and Analysis > Conversions screen in your AdWords account, or the AdWords API Conversion Tracker service:
The script creates a new conversion with the following parameters:
- name: The name of the new conversion, which must be unique within the account.
- category: The conversion category; chosen from
- ctcLookbackWindow: The maximum amount of days after a click that a conversion can be registered. The must be an integer between 7 and 90.
- viewthroughLookbackWindow: The maximum amount of days after a click that a view through conversion can be registered. The must be an integer between 1 and 30.
After running this code, you should see a new conversion in your AdWords account:
Once you've set up the conversion, you don't need to run the code again (you'll get a
ConversionTrackingError.DUPLICATE_NAME if you do).
Collecting the Click Ids on Your Website
You link your offline conversions to AdWords clicks using a click id that Google appends to your destination URLs. This is the same GclId that Google has used with Analytics for a long time, but you can now use it in your own tracking systems. Note that if your Google Analytics account isn't already linked to your AdWords account, then you'll need to enable URL auto-tagging in AdWords (there's no way to do this in the API at the moment).
This code's quite rudimentary, but should capture the click id in a cookie called
gclid that you can use in a PHP form:
Uploading the Conversions to AdWords
However you have stored your click ids, for the next step I'll assume you have it in an associative array:
This represents each conversion using an associative array with three entries:
- gclid: The click id extracted from the landing page.
- date: The timestamp of the conversion event.
- value: The revenue associated with the conversion. You can omit this if you don't want to assign a value to the conversion.
This code just creates an
OfflineConversionFeed for each of your offline conversions and uploads them using the
mutate() operation of the
OfflineConversionFeedService. The script formats each conversion timestamp as required by the API, so the 12:30 on the 9th of November, 2013 becomes
The conversions will take a while to turn up in your account, but after around three hours you should see the conversion appearing in reports:
Common Issues with Conversion Uploads
There's a few things you should note about the uploads in case you have any problems:
- You need to wait around four to six hours after a click before uploading its gclid, or you will get an
- The conversion date needs to be after the time of the click—or you'll get an
OfflineConversionError.CONVERSION_PRECEDES_CLICKerror—before the end of the
ctcLookbackWindow—or you'll get an
OfflineConversionError.EXPIRED_CLICKerror—and not a future date—or you'll get a
DateError.LATER_THAN_MAXIMUM_DATEerror. You should check that you're using the same timezone as the AdWords account into which you're importing conversions as that can cause these types of problem.
- AdWords will only register the first successful uploaded conversion for a single click, conversion type, and time, but you can upload multiple conversions for the same click with a different conversion type/time. So, for example, if you upload a conversion for a click on the Phone Calls type on the 9th of November, 2013 at 18:35 with a value of $10, and another for the Phone Calls type on the 9th of November, 2013 at 18:35 with a value of $5, only the $10 value will be registered (both one-per-click and many-per-click); however, if you change the time to 18:36, there will be two many-per-click conversions with a total value of $15.
- You need to ensure that the name of the conversion type you use is exactly the same as the one in your AdWords account, including the same case; Phone Calls is not the same as phone calls or phone call etc. You'll get an
OfflineConversionError.INVALID_CONVERSION_TYPEerror if there's a problem.
AdWords Conversion Import Script
Here's a full version of the script including the boilerplate AdWords API authentication code, which you can find out about in my OAuth Playground Tutorial: