Conversion Tracking

Implementation

Summary

There are three pieces to a conversion tracking implementation:

  • Collecting the rwg_token from the landing page / app entry point.
  • Persisting the rwg_token for the appropriate attribution window
  • Sending a conversion event at checkout

This conversion tracking implementation does not require you to use Google Analytics or any other 3rd party javascript.

Before beginning work on your conversion tracking implementation, you should decide if you're going to track conversions at the device level or user level:

  • The device level includes using browser cookies, local storage, app local storage, or any other method that can persist the token for the 30 day attribution window. Because the token would be stored locally on the user's device, if the user changes the device they are using, clears their local storage or cookies, or is using a private browsing or incognito mode the conversion event may not be properly attributed. When using the device level conversion tracking, you must re-implement this across every supported surface (including mobile).
  • The user level includes persisting it in your application database, through a server-side analytics system or other server-side systems. Because the token would be stored on the server side, if the user changes the device they are using, clears their local storage or cookies, or is using a private browsing or incognito mode the conversion event is still be attributed once the user logs back in. When using user level conversion tracking, depending on your system's architecture you may be able to implement this once on your server side and reuse it across all supported surfaces.

Collecting the rwg_token

Each time Google surfaces an action_link you have provided through the Feeds, that URL is modified to include a unique query parameter: rwg_token. The rwg_token value is an encoded string which contains some metadata about the link the user clicked. You should store this token, and pass it back as part of the conversion event.

On each landing page / app entry point you must parse the value set for the rwg_token query parameter and store it. Requirements for storing this parameter are described in the step, Persisting the rwg_token.

An example for how this token can be parsed for device level tracking through the browser is included below. Alternatively, you could collect this token on the server side when responding to the request:

<script>
  var query = location.search.substring(1);
  var params = query.split('&');
  var rwgToken = undefined;
  for (var i = 0; i < params.length; ++i) {
    var pair = params[i].split('=');
    if (pair[0] == 'rwg_token') {
      rwgToken = decodeURIComponent(pair[1]);
      break;
    }
  }
</script>

Persisting the rwg_token

You will be required to persist the rwg_token URL parameter, which will be appended to all action links provided by you, for a total duration of 30 days. The value of the rwg_token should be stored and returned without any edits.

Along with the rwg_token, you will need to store the merchant_id associated with the action link.

If there is an existing token persisted from a previous visit, the earlier rwg_token and merchant_id should be replaced, and the 30 day window for storage should be reset.

When persisting the above pair, you may either store the values at the device level or at the user level:

  • The device level includes using browser cookies, local storage, app local storage, or any other method that can persist the token for the 30 day attribution window.
  • The user level includes persisting it in your application database, through a server-side analytics system or other server-side systems.

Below is an example of device level conversion tracking, storing these values in a web browser using a 1st party cookie. This example assumes you have parsed the token value into a variable as in the example above. To use this example, you need to update 'rootdomain' to your domain.

<script>
  if (typeof rwg_token !== 'undefined') {
    document.cookie =
    "_rwg_token=" + rwg_token + ";_merchant_id="+merchantid +";max-age=2592000;domain=rootdomain.com;path=/";
  }
</script>

When using user level conversion tracking the rwg_token + merchant_id should be stored on the server and associated with the user.

Sending Conversion Data

When a user completes a transaction which is attributable to a Google Place Action link, you must send an HTTP POST request to the conversion endpoint. There are two endpoints, one for the production environment and one for the sandbox environment.

  • Production: https://www.google.com/maps/conversion/collect
  • Sandbox: https://www.google.com/maps/conversion/debug/collect

The post body should be a JSON encoded object in the format:

{
  "conversion_partner_id": <partnerId>,
  "rwg_token": <rwg_token_val>
  "merchant_changed": 1|2
}

The merchant_changed value is used to determine if the merchant has been changed from the initial redirect merchant. There are two values which can be passed

Merchant Change Value Requirement
1 This value should be used when a user has left the original merchant's website and completed a purchase through your platform with a different merchant
2 This value should be used when the customer completed a transaction through the original Entity (Merchant).

In both the sandbox and production environments you are required to provide a valid rwg_token when sending a conversion event. For testing purposes, use the following test token in both environments until you launch:

ADQ7psRE9YyDSVR6YpfD-fYdxoFYVKS1xeTvXdSxqF8a3bnk0W62eMEnUjoNPwjhNHG0elwBnM1awTjr9vXET8yOowCeuODjwA==

A full example of device level conversion tracking (using a cookie on the user's device) in javascript of how to make this post request is included below:

const partnerId = XXXXXXXXXX;

const endpoint = https://www.google.com/maps/conversion/collect;

const rwgTokenCookie = document.cookie
  .split('; ')
  .find(row => row.startsWith('_rwg_token='));

if (typeof rwgTokenCookie !== 'undefined') {
  const rwgTokenVal = rwgTokenCookie.split('=')[1];
  fetch(endpoint, {
    method: "POST",
    body: JSON.stringify({
      conversion_partner_id: partnerId,
      rwg_token: rwgTokenVal,
      Merchant_changed: merchantChanged
    })
  });
}

When using user level conversion tracking, you should retrieve the token which is associated with the user (regardless of the surface they are on) from your server side storage mechanism and send the token using the same production or sandbox endpoints.

Conversion Attribution Requirements

Google's required standard for conversion attribution is a 30-day attribution window for any interaction with a place link, at any store.

This attribution window means that Google would expect a conversion event to be sent in any of the following scenarios:

  • A user follows a place action link and places an order for the same merchant in the same session(Merchant Change Value = 2 )
  • A user follows a place action link and then returns from a different channel within the 30 day window to place an order for the same merchant. ( Merchant Change Value = 2 )
  • A user follows a place action link and then places an order at a different store, either within the same session or a different session within a 30 day window. ( Merchant Change Value = 1 )

Additionally, Google expects conversion events to be sent from all surfaces a user can land into from a place action link. Including:

  • Desktop or mobile web applications
  • Mobile apps, either through an app deep link or a registered app-intent for your domain

If the token is stored at the user level (see persisting the token), it is expected that you provide cross-device attribution. That is, a user who follows an action link from the desktop and then completes the transaction on mobile (using the same user account), should trigger a conversion event.

If the token is stored exclusively at the device level, such as in browser cookies, it is not expected that you provide cross-device attribution. In this case, each device would have a separate token persisted if the user had followed an action link on that device, and each device would follow the attribution rules separately.