Discover 201008: CustomerSyncService - So what’s new?

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);

The result will be a CustomerChangeData object with the entities that changed over the last day for the campaign specified; for the date time range you specified and the single campaign ID, you would only get one CampaignChangeData object back from within the 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:

1. Get a full list of all current campaigns by performing a CampaignService.get with an empty selector and collect the IDs.
2. Choose a date time range. This could depend on how granular you want your results, or when you last ran the service.
3. Create a CustomerSyncSelector incorporating all of the campaign IDs and the date time range.
4. Run CustomerSyncService.get with the selector.
5. Process the results by traversing the CustomerChangeData object.
6. Fetch the new data of the entties for all of the IDs within the CustomerChangeData hierarchy using their respective services

The goal of the 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>

Notice that not only is the status field is set to 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>

Notice here that since the campaign already existed and the budget was changed, the status is 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