We recently released the second part of the v201008 version of the AdWords API and with it the CustomerSyncService - the AdWords API’s first service to determine the entities that were changed in your account. In this blog post, I’ll discuss our goals for the new service and provide a few examples illustrating how to integrate it with your system.
At our developer workshops, we received lots of great feedback about what you’d eventually like to see in this service. Please keep sharing your feedback with us on our forum.
Getting started
Central to the service is the CustomerSyncService.get method. You’ll use this method to retrieve all entities that have changed within the account for a given date time range and set of campaign IDs. As an example, to select all changes to campaign with id 12345 yesterday (today being October 27th), you would do something like:
// Create date time range.
DateTimeRange dateTimeRange = new DateTimeRange();
dateTimeRange.setMin(“20101026 000000”);
dateTimeRange.setMax(“20101027 000000”);
// Create selector.
CustomerSyncSelector selector = new CustomerSyncSelector();
selector.setDateTimeRange(dateTimeRange);
selector.setCampaignIds(new long[] {12345L});
// Get all account changes for campaign.
CustomerChangeData accountChanges = customerSyncService.get(selector);accountChanges variable. If you had specified more than one campaign ID, you would get back one CampaignChangeData object per campaign.Syncing up
The general way you can use the service is to:
- Get a full list of all current campaigns by performing a CampaignService.get with an empty selector and collect the IDs.
- Choose a date time range. This could depend on how granular you want your results, or when you last ran the service.
- Create a
CustomerSyncSelectorincorporating all of the campaign IDs and the date time range. - Run CustomerSyncService.get with the selector.
- Process the results by traversing the
CustomerChangeDataobject. - Fetch the new data of the entties for all of the IDs within the
CustomerChangeDatahierarchy using their respective services
CustomerSyncService is to give you a consolidated overview of what has changed over a time period; changes will be grouped together based on their overall outcome. Because of this, the dateTimeRange property will largely determine how your results are consolidated. If you added a campaign to your account on the previous day, for example, you would receive a CampaignChangeData object with the campaignChangedStatus field set to NEW. Imagine now that you changed the campaign later that day as well. If the service returned a single
CustomerChangeData object for each change, there would be two objects within the CustomerChangeData - one for the “new” event and one for the “modified” event. Instead, the two events will be consolidated into one object with the status set to NEW, not FIELDS_CHANGED. If you, however, split the service call into two date time ranges, one before the modification and one after, the first call would return a CampaignChangeData object with the status of NEW, and the second call would return a CampaignChangeData object with the status of FIELDS_CHANGED.The same consolidation principle applies to child objects also. As an example, imagine you create a campaign, modify it later that day, then create an ad group, and then also modify that ad group later that day. The resulting
CustomerChangeData object would resemble:
<rval>
...
<changedCampaigns>
<status>NEW</status>
...
</changedCampaigns>
</rval>NEW, not FIELDS_CHANGED, but also ad groups have been omitted even though they were also modified that day. Since the campaign is new, all of the entities within that object would also be new. Because of this, you would only get 1 CustomerChangeData object with no AdGroupChangeData within in it.As a final example, imagine that you create an ad group into an existing campaign and modify the budget of the campaign during the same time period. The resulting
CustomerChangeData object would be:
<rval>
...
<changedCampaigns>
<status>FIELDS_MODIFIED</status>
...
<changedAdGroups>
<status>NEW</status>
...
</changedAdGroups>
</changedCampaigns>
</rval>FIELDS_MODIFIED. If the ad group had just been added, and the campaign budget left alone, the status for the campaign would be FIELDS_UNMODIFIED. Because you see the status is not FIELDS_UNMODIFIED, you know to fetch the campaign from the API, as well as the ad group, while syncing.We believe the CustomerSyncService provides a great new way to save you time from scouring your account for changes. We’re looking forward to your feedback on our forum and look forward to seeing what you create with it.
-- Adam Rogal, AdWords API Team
