Conversion Tracking

Figure 2: Conversion Tracking Overview

Summary

Conversion Tracking is intended to keep track of conversions initiated by Google through one of our Action Center Integrations. This is vital to keep your integration healthy, running, and may influence ranking on certain pages. Each time Google surfaces an action_link, that URL is modified to include a unique query parameter: rwg_token. It's up to you to store that token and return the appropriate values when a user completes a booking.

To complete the integration you need to complete the following:

  1. Collect and Store the rwg_token.
  2. Collect and Store the merchant.
  3. Return the rwg_token and the merchant_change values.
  4. Test and Verify Conversion Tracking.

Collect and Store the rwg_token.

To complete this integration you must collect and store the rwg_token for up to 30 days of the initial Google referral. The rwg_token value is an encoded string which contains some metadata about the link and the merchant that generated that action link, it's important to note that no user data is stored or encrypted in the token.

Token Collection

When a user is directed to your booking page, a new query parameter, rwg_token, will be appended to the URL provided. In your booking page, you must parse the value. An example for how this token can be parsed for device level tracking through the browser is included.

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

The query parameter appended to your URL will be an encrypted token, see the following example of a rwg_token. Use this sample token to ensure your parsing the token correctly, including any special characters such as "=". The following is an sample of what a typical token will be like.

AJKvS9WeONmWKEwjG0--HdpzMq0yAVNL8KMxbb44QtbcxMhSx_NUud5b8PLUBFehAIxOBO-iYRIJOknEFkIJmdsofdVJ6uOweQ==

Token Storage

When storing the rwg_token, there are two different levels at which you can implement conversion tracking, device level and user level. Where you decide to store the token is your decision but you must store the token for 30 days since the initial referral.

The next example is 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 Token Storage example. Make sure to update rootdomain.com with your domain.

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

Consider the following when deciding where to store the rwg_token.

Device-Level Storage

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

User-Level Storage

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.

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.

Refresh the Token

When a user is referred by Google to the same merchant, if an existing token is stored, the token is then replaced with the new token from the latest referral. When the token is replaced, the 30 day window of the token storage is then reset and any new conversions for this merchant should be attributed to the latest token.

Refer to our Conversion Attribution Requirements for more details.

Collect and Store the merchant.

When a user is directed to your booking page, you must implement logic that would find and capture the merchant. Typically partners add merchant metadata or merchant_id to their action links and use that to identify and store the merchant. We recommend you store the merchant_id (or the selected identifier) alongside the rwg_token so when a user confirms a booking you can refer to the merchant before sending the completed conversion request. Similar to the token storage window, the merchant must be saved with the token for 30 days of the initial referral.

The next examples adjusts the previously stored rwg_token. This assumes you're parsing the merchant from metadata in the provided URL and either saving it as a merchant_id or matching it to an existing merchant_id.

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

Return the rwg_token and merchant_change values.

When a use completes a booking that began from an Action Link referral, 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

When sending a conversion event you must include the stored rwg_token and a merchant_change value of 1 or 2, more details on merchant_change see Return the Merchant Change Value.

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

{
  "conversion_partner_id": "XXXXXXX",
  "rwg_token": "AJKvS9WeONmWKEwjG0--HdpzMq0yAVNL8KMxbb44QtbcxMhSx_NUud5b8PLUBFehAIxOBO-iYRIJOknEFkIJmdsofdVJ6uOweQ==",
  "merchant_changed": "2"
}

The next example include device-level conversion tracking using a cookie on the user's device, it's written in Javascript:

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

Return the Merchant Change Value

The merchant_changed value is used to determine if the merchant has been changed from the initial redirect merchant. Changing merchants is common if your landing page is within a platform that includes other merchants. In this case, if a user was referred to your platform by Google and decided to navigate to a different merchant and complete a booking, we want to know that a conversion happened but with a separate merchant, we don't need to know the merchant just that a conversion event happened and the merchant was different, we use a Boolean to identify whether or not a merchant has changed.

When deciding what value to assign merchant_change, you will need to take the original merchant saved in Collect and Store the Merchant and check if the merchant has changed, then reference the following table when assigning the value.

If your booking page is not within a platform or users are unable to navigate to a different merchant, you may hardcode the value of these requests to 2. This is common for partners who integrate their booking pages into their merchant's website or have custom landing pages for processing bookings.

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

Test and Verify Conversion Tracking.

To ensure that your implementation of conversion tracking is correct, you'll need to run the following test. Make sure to use Action Links tied to your merchants and the requests are made in a private or incognito window to ensure any previous token associated with that user is cleared.

  1. Complete a booking just using an Action Link
    • Direct bookings with no referral or previous stored tokens shouldn't result in any request sent to Google.
  2. Complete a booking using a link with an appended rwg_token.
    • Ensure the request is successful and sent with the rwg_token and merchant_change value of 2
    • Ensure you're storing the rwg_token for 30 days
  3. Complete a new booking with the same merchant using a new rwg_token.
    • Ensure the request is successful and sent with the new rwg_token and merchant_change value of 2
    • Ensure the attribution storage window of the token is refreshed for 30 days
  4. Navigate directly to the booking page of the merchant you've been testing and make a new booking without an appended rwg_token.
    • Ensure that the request is sent with the previously stored rwg_token and the merchant_change value is 2

If you're a platform with the ability for users to checkout using a different merchant, test the following.

  1. Go to the merchant's booking page using a link with an appended rwg_token, then proceed to navigate to a different merchant and make a booking.
    • Ensure that the request is sent with the rwg_token and merchant_change value of 1

When testing send the 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

You'll need to append the following token to your action link or URL:

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

Use the following token for tests that require additional tokens.

rwg_token=AJKvS9U2QfiQanHFQrlJxBjD0AyFany3qpaJVEWOcY4nHqY_UkLYFFDj6RIa-EXS1iEmV8gtFPG6v1cU1jnusJK66ijXXnaqkQ%3D%3D

When you've sent the successful conversion events, you can see them aggregated in the Action Center under the Conversion Tracking Dashboard. Keep in mind that conversions may take up to an hour to appear in the dashboard.

conversion-tracking-dashboard

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.

Previous
Feeds
Next
Integration Review