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:
- Collect and Store the
rwg_token
. - Collect and Store the merchant.
- Return the
rwg_token
and themerchant_change
values. - 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.
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.
- 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.
- Complete a booking using a link with an appended
rwg_token
.- Ensure the request is successful and sent with the
rwg_token
andmerchant_change
value of2
- Ensure you're storing the
rwg_token
for 30 days
- Ensure the request is successful and sent with the
- 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
andmerchant_change
value of2
- Ensure the attribution storage window of the token is refreshed for 30 days
- Ensure the request is successful and sent with the new
- 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 themerchant_change
value is2
- Ensure that the request is sent with the previously stored
If you're a platform with the ability for users to checkout using a different merchant, test the following.
- 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
andmerchant_change
value of1
- Ensure that the request is sent with the
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 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.