Forward Compatibility Maps

The forwardCompatibilityMap field allows you to explore cutting-edge functionality before it is formally exposed in the API. This field is included in some of the major API entities (for example, Campaign).

forwardCompatibilityMap is of type String_StringMapEntry, representing a mapping of string to string. The mapping is used to get and set 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. Objects that have the forwardCompatibilityMap field include Campaign, AdGroup, and AdGroupAd.

Reading the map

You don't need to reference a forwardCompatibilityMap field as part of your Selector.fields array. If there's at least one key exposed in the API version and service you're using, the forwardCompatibilityMap field will be present in the response.

A map may contain a set of keys, one 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 may see the key Ad.devicePreferred in the map for AdGroupAd, but in actuality, that key belongs to the Ad object (a descendant of AdGroupAd ).

Map values are of type string, but depending on the associated key and the attribute it represents, values can be string representations of other basic data types such as integers or booleans. You may need to convert the type before using them.

Get example

Here is an example of calling the get() method in CampaignService to retrieve the Campaign.enhanced key from its forwardCompatibilityMap. This example is derived from our 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.");
 }

Changing properties from the map

Mutating keys, such as the Campaign.enhanced key, through forwardCompatibilityMap is no different than with any other attribute: You just need to call the mutate() method, making sure the forwardCompatibilityMap is populated with the keys and values you want changed. The regular ADD and SET mutate operations accept forwardCompatibilityMap data, but may require a few provisions.

Be sure to pass a valid value for a key or an ApiException will result. Also, be sure the key name is correct, as wrong or undefined key names are silently ignored by the API, and can cause errors that are difficult to diagnose.

Mutate 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 derived from 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 errors that are difficult to diagnose, since the API will silently allow passing the invalid key name.

It's also worth noting that keys are tied to API versions. A key that's valid in one version will cease to be accepted in a future version when 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're expecting to see in the map.

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

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

I know there's 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 and accepted only in API versions that don’t have the functionality already exposed.

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.