Using Forward Compatibility Maps

This page covers the use of Forward Compatibility Maps in the AdWords API.

1. Understanding forward compatibility maps
2. Reading the map
3. Mutating properties using the map
4. Handling errors
5. FAQ
6. Available ForwardCompatibilityMap keys

Understanding forward compatibility maps

The forwardCompatibilityMap field allows you to explore cutting edge functionality even before it is formally exposed in the API. This field is included in some of the key API entities (e.g. in the Campaign object).

forwardCompatibilityMap is of type String_StringMapEntry[]. It represents a mapping of string to string, and is used to get and set simple properties on API entities — properties that are not yet available as formal attributes of the object or its descendants. These properties are exposed through keys in forwardCompatibilityMap; refer to this table for the list of available keys. Several objects in the API, such as Campaigns, AdGroups, AdGroupAds and others, already expose the forwardCompatibilityMap field.

This guide will show you how to read and update from the forward compatibility map.

Reading the map

You access the data in the forward compatibility map in the same manner as any other field from the object, except that you don’t need to reference the forwardCompatibilityMap field as part of the Selector.fields array. In other words, if there’s at least one key exposed in the API version and service being used, the forwardCompatibilityMap field will always be present in the response.

The forwardCompatibilityMap might contain a set of keys, different for each object type, that are exposed as an extension of the formal attributes of the object or one of its descendants. A key in an object's forwardCompatibilityMap may reference an attribute of the object's descendant rather than the object itself. For example, you can see the key Ad.devicePreferred in AdGroupAd's map, but in actuality, that key belongs to the Ad object (one of AdGroupAd's descendants).

Map values are of type string, but depending on the associated key and the attribute it is representing, these values can be string representations of other basic data types such as integers or booleans. In certain cases, type conversion may be needed on the client side.

The following is an example of a get call against CampaignService to retrieve the Campaign.enhanced key from its forwardCompatibilityMap. This example is based on the Java client library.

 // Get the CampaignService.
 CampaignServiceInterface campaignService =
     adWordsServices.get(session, CampaignServiceInterface.class);

 // Create selector.
 Selector selector = new Selector();
 // Set the selector fields.
 // Notice there is no need to explicitly request the
 // forwardCompatibilityMap, indeed adding to the list of fields
 // will throw an error.
 selector.setFields(new String[] {"Id", "Name"});

 CampaignPage page = campaignService.get(selector);

 // Display campaigns.
 if (page.getEntries() != null) {
   for (Campaign campaign : page.getEntries()) {
     Map forwardCompatibilityMap =
         Maps.toMap(campaign.getForwardCompatibilityMap());
     System.out.println(String.format(
         "Campaign ID %d has enhanced value of '%s'",
         campaign.getId(),
         forwardCompatibilityMap.get("Campaign.enhanced")));
   }
 } else {
   System.out.println("No campaigns were found.");
 }

Mutating properties using the map

Mutating keys, such as the Campaign.enhanced key shown in the previous example, through forwardCompatibilityMap is no different than with any other attribute. You just need to construct a regular mutate call making sure the forwardCompatibilityMap is populated with the keys and values you want changed. The regular ADD and SET mutate operations accept forwardCompatibilityMap data with a few provisions as described in the Notes column of the table below.

Be sure to always pass a valid value for a key, as passing the wrong value will result in an ApiException. Also, be especially sure that the right key name is used, as using a wrong/undefined key name will be silently ignored by the API, possibly causing errors that are difficult to debug. Refer to the handling errors section of this guide for more information.

Example
The following example demonstrates how to change a campaign to an enhanced campaign by sending the Campaign.enhanced key with a value of "true" in the forwardCompatibilityMap. This example is based on the Java client library.

 // This is an example on how to enhance a campaign using the
 // CampaignService and the forwardCompatibilityMap field.

 // Get the CampaignService.
 CampaignServiceInterface campaignService =
     adWordsServices.get(session, CampaignServiceInterface.class);

 // Create campaign with updated status.
 Campaign campaign = new Campaign();
 campaign.setId(campaignId);
 // Set the "Campaign.enhanced" as "true" to update the campaign.
 campaign.setForwardCompatibilityMap(new String_StringMapEntry[] {
     new String_StringMapEntry("Campaign.enhanced",
         Boolean.TRUE.toString())});

 // Create operations.
 CampaignOperation operation = new CampaignOperation();
 operation.setOperand(campaign);
 operation.setOperator(Operator.SET);

 CampaignOperation[] operations =
     new CampaignOperation[] {operation};

 // Update campaign.
 CampaignReturnValue result = campaignService.mutate(operations);

Handling errors

Certain operations, such as passing an invalid value of a key in the forwardCompatibilityMap, will result in an ApiException containing an ApiError. This error will contain the fieldPath pointing to the forwardCompatibilityMap and the trigger populated with the offending value.

Passing an invalid key name may result in difficult to diagnose errors since the API will silently allow it.

It is also worth noting that keys are tied to API versions. A key that is valid to a certain version will cease to be accepted in a future version as soon as its functionality is formally implemented in the API. If a key is passed to an API version that no longer accepts it, an ApiException will be returned.

FAQ

How do I request the forwardCompatibilityMap to be populated in the response? I don’t see a field name for it in the documentation.

You don’t have to request it as part of your Selector.fields, it will get populated if there is data attached to the object that should be returned in the map.

Why isn’t the forwardCompatibilityMap being populated?

Generally, because the object has no data attached to the key you are expecting to see in the map.

Will I get an error if I send the wrong key in the map?

No, you need to be careful when specifying the name of the key because the API will silently ignore unrecognized keys.

I know there is a new field/key supported in an object but I don’t see the object having a forwardCompatibilityMap.

Only top level API entities, such as Campaign, AdGroup and AdGroupAd, expose the forwardCompatibilityMap. But some keys affect underlying objects.

What happens if I send the wrong value in the map?

If you set the right key but use an unsupported value, an ApiException will be returned.

Are keys exposed across all API versions?

No, keys are exposed/accepted only on API versions that don’t have the functionality already exposed.

Available ForwardCompatibilityMap keys