Conversion Tracking

Warning: Ensure that as part of conversion data, user Personal Identification Information (PII) is not sent to Google.

Implementation

Summary

There are three pieces to a conversion tracking implementation:

• Collecting the rwg_token and merchant_id from the landing page / app entry point.
• Persisting the rwg_token and merchant_id for the appropriate attribution window.
• Compare persisted merchant_id and merchant_id at conversion time (booking completed).
• Sending a conversion event at conversion time (booking completed).

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

Key Point: There are two different levels at which you can implement conversion tracking, device level and user level. Both are supported during this integration, and you can choose based on your product architecture.

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 but no user data. 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:

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

Collecting the merchant_id

If you implement the conversion tracking logic in the frontend, on the landing page, you must implement a custom script that would find and capture the merchant_id. Usually, the merchant_id might already be present on the landing page or in the URL so you can capture it from there. If not, you must find a way to expose it somewhere so it's capturable which would likely imply backend changes.

If you implement the conversion tracking logic in the backend, you may find the merchant_id alongside the data that queries your internal system to generate the frontend page.

This merchant_id must be the same as the one you have shared with Google in your feed.

Note: In the rare case that your frontend experience does not allow the user to switch between merchants (may happen for white label websites that does not have a "home" button to return to a selection of merchants). You may skip the merchant_id capture and assume the merchant_id did not change ("merchant_changed": 2) as it's impossible for users to jump between merchants in their booking journey.

Persisting the rwg_token and merchant_id

Note: Persisting the rwg_token is key to correctly implementing the required attribution window. For more details on the attribution requirements see the section Conversion Attribution Requirements below.

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.com to your domain.

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

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
}

Example (unchanged merchant with the test token for partner 20123456):

{
  "conversion_partner_id": 20123456,
  "rwg_token": "AJKvS9WeONmWKEwjG0--HdpzMq0yAVNL8KMxbb44QtbcxMhSx_NUud5b8PLUBFehAIxOBO-iYRIJOknEFkIJmdsofdVJ6uOweQ==",
  "merchant_changed": 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:

AJKvS9WeONmWKEwjG0--HdpzMq0yAVNL8KMxbb44QtbcxMhSx_NUud5b8PLUBFehAIxOBO-iYRIJOknEFkIJmdsofdVJ6uOweQ==

To test in Sandbox, you need to manually append the following URL parameter to your Sandbox links:

rwg_token=AJKvS9WeONmWKEwjG0--HdpzMq0yAVNL8KMxbb44QtbcxMhSx_NUud5b8PLUBFehAIxOBO-iYRIJOknEFkIJmdsofdVJ6uOweQ%3D%3D

Caution: In production you shouldn't send conversion events that are not attributed to this integration. Be sure to check for a valid and unexpired rwg_token value before sending the event.

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

Caution: The only accepted MIME Content-Type is text/plain. Don't set any Content-Type in the header. If you do, you will get a CORS error.

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.

Note: Conversion events can be sent from a web or app client, or from the server. You can make this decision according to your needs and according to where the token is stored, as long as a conversion event is sent exactly once per conversion, and includes a valid rwg_token value.

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.

Note: This attribution framework may be different from how your analytics system attributes conversions. This system is designed to operate independently of any conversion tracking you are doing in your systems, and shouldn't affect your internal analytics.

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.