The purchase-details variable provides information about the products sold in a given transaction. You can add the variable to a Floodlight event snippet, Floodlight tag, the Google Tag Manager data layer, or a Google Tag Manager macro.
Depending on how you add the variable, use one of the following formats:
-
If you're using the Google tag, format the purchase-details variable as a JSON object directly in the Floodlight event snippet.
- If you're using a Floodlight Iframe or image tag, or passing the data to Google Tag Manager as a macro, format the purchase-details variable as a String divided into a set of fields.
-
If you're pushing the data to Google Tag Manager's data layer, format the variable as a JSON object with purchase-detail fields.
Requirements for the JSON format in a Floodlight event snippet
If you use the Google tag, purchase details should be specified in the event snippet as a JSON items array, plus country and language fields. Each item in the array contains the following fields:
idprice-
quantity
For example:
<!--
Event snippet for Thank You on http://example.com/thanks: Please do not remove.
Place this snippet on pages with events you’re tracking.
Creation date: 11/01/2017
-->
<script>
gtag('event', 'purchase',
{
'allow_custom_scripts': true,
'send_to': 'DC-1234567/group1/thank123+transactions',
'transaction_id': '012345',
'value': 129.97,
'items': [
{ 'id': '123456755559',
'price': '19.99',
'quantity': 1
},
{ 'id': '123456788889',
'price': '54.00',
'quantity': 2
}
],
'country': 'us',
'language': 'en'
}
);
</script>
<noscript>
<img src="https://ad.doubleclick.net/ddm/activity/src=1234567;type=group1;cat=thank123;
qty=1;cost=129.97;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=;npa=;
ord=012345;prd=i1:123456755559|p1:19.99|q1:1|i2:123456788889|p2:54.0|q2:2|c:us|l:en?" width="1" height="1" alt="">
</noscript>
<!-- End of event snippet: Please do not remove -->
Note: Event snippets generated by Search Ads 360 include an optional <noscript> tag that contains a Floodlight image tag. This tag is used to report conversions in browsers that don't support JavaScript. If your site supports browsers that haven't enabled JavaScript, it's recommended that you update the Floodlight image tag to include purchase details as shown in the example.
Requirements for the JSON format in the data layer
If you use Google Tag Manager, the purchase-detail fields should be specified as elements in a JSON ecommerce.purchase.products array:
'ecommerce':{
'purchase':{
'products': [{
'id': 'String',
'price': 'Floating point',
'quantity': Integer,
'country': 'String', // Optional
'language': 'String', // Optional
'accountId': 'String' // Optional
},
{
… // Each SKU (product) in the transaction
// is in its own array item.
}]
}
}'
Note that the field names for this JSON object are different from the JSON object you use if you're adding the purchase-details variable to a Floodlight event snippet.
When you push purchase details to the data layer, you'll actually be storing the data in the same object that Google Analytics can use to report the products that have been purchased on your site. That is, if you're using both Search Ads 360 and Google Analytics to report purchase details, your web developer can use the same object to store the data for both products.
Requirements for the String format
In the String format, each purchase-detail field should be specified as a key-value pair in the following format:
[field ID][index]:[value]
- [field ID] identifies the type of value being reported.
- [index] indicates the item for which the value is being reported.
- [value] provides information about the sale of the product.
Separate each field with a | (pipe). For example,
i1:123456755559|p1:19.99|q1:1|i2:123456788889|p2:54.0|q2:2
Purchase-detail fields
|
Field |
ID in String format |
Type |
Required |
Description |
|
|
|
String |
Yes |
The ID of the product that has been sold. The ID must match the item id from Google Merchant Center. |
|
|
|
Floating point |
Yes |
Price per unit of the product that has been sold. Do not include a currency symbol. |
|
|
|
Integer |
Yes |
The quantity of units of the product that has been sold. |
|
|
|
String (ISO 3166 country code) |
No |
The country registered for the Merchant Center feed that contains data about the product. This field is needed only when item IDs are not unique across multiple Merchant Center feeds. Specify the country only once for each product (it is not a repeated field). If the field isn’t specified, Search Ads 360 chooses a Merchant Center feed that contains the product ID and uses that feed's attributes for the products sold dimensions. |
|
|
|
String (ISO 639 language code) |
No |
The language registered for the Merchant Center feed that contains data about the product. This field is needed only when item IDs are not unique across multiple Merchant Center feeds. If the field isn’t specified, Search Ads 360 chooses a Merchant Center feed that contains the product ID and uses that feed's attributes for the products sold dimensions. |
Special characters and URL encoding
The : (colon) and | (pipe) are used as field delimiters in the String format. Search Ads 360 cannot accept data that includes these characters as values in a field, even if you're using one of the JSON formats.
As with all Floodlight data, the following characters also are not accepted:
;, <, >, ?
Suppose a transaction includes the following items:
-
Item 1
- Name: m-dress-orange-xl
- UPC: 123456755559
- Price per item: $19.99
- Quantity: 1
-
Item 2
- Name: m-polo-green-l
- UPC: 123456788889
- Price per item: $54
- Quantity: 2
The purchase-details variable in an event snippet would contain the following fields:
'items': [
{ 'id': '123456755559',
'price': '19.99',
'quantity': 1
},
{ 'id': '123456788889',
'price': '54.00',
'quantity': 2
}
]
Here's how the purchase details variable appears in a Floodlight iframe tag:
i1:123456755559|p1:19.99|q1:1|i2:123456788889|p2:54.0|q2:2
In addition to the purchase-details variable, the Floodlight tag or event snippet would also specify the following data:
-
ID of the Floodlight activity group
-
ID of the Floodlight activity
-
Transaction ID (Order ID)
-
Total value of the transaction: $129.97 = (1*$19.99 + 2*$54)
-
Quantity: 3 (you can define the exact meaning of this field. You might consider using it to report on the total cart size.)
-
Any other custom Floodlight variables
The final google tag with the event snippet would look like this:
<!--
Start of global snippet: Please do not remove
Place this snippet between the <head> and </head> tags on every page of your site.
-->
<!-- Google tag (gtag.js) - DoubleClick -->
<script async src="https://googletagmanager.com/gtag/js?id=DC-1234567"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments)};
gtag('js', new Date());
gtag('config', 'DC-1234567');
</script>
<!-- End of global snippet: Please do not remove -->
<!--
Event snippet for Thank You on http://example.com/thanks: Please do not remove.
Place this snippet on pages with events you’re tracking.
Creation date: 11/01/2017
-->
<script>
gtag('event', 'purchase',
{
'allow_custom_scripts': true,
'send_to': 'DC-1234567/group1/thank123+transactions',
'transaction_id': '012345',
'value': 129.97,
'items': [
{ 'id': '123456755559',
'price': '19.99',
'quantity': 1
},
{ 'id': '123456788889',
'price': '54.00',
'quantity': 2
}
],
'country': 'us',
'language': 'en'
}
);
</script>
<noscript>
<img src="https://ad.doubleclick.net/ddm/activity/src=1234567;type=group1;cat=thank123;
qty=1;cost=129.97;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=;npa=;
ord=012345;prd=i1:123456755559|p1:19.99|q1:1|i2:123456788889|p2:54.0|q2:2|c:us|l:en?" width="1" height="1" alt="">
</noscript>
<!-- End of event snippet: Please do not remove -->
Here's an example of Floodlight Iframe tag with a purchase details variable:
<iframe src="https://ad.doubleclick.net/activity;src=12345;type=group-;cat=activity;ord=12345;qty=3;cost=140;prd=i1:123456755559
|p1:19.99|q1:1|i2:123456788889|p2:54.0|q2:2?" width="1" height="1" frameborder="0" style="display:none"></iframe>
You can use Merchant Center to submit your products in multiple feeds, each targeted to a specific language and country. For example, if you sell the same group of products in the US and Canada, you can set up one feed with prices and descriptions for the US, another feed with Canadian prices and descriptions in French, and a third feed with Canadian prices and descriptions in English.
When you submit feeds with the same product IDs but different target languages or countries, you'll need to include the language and country code in the purchase-details variable. For example, this items array and country and language fields in the event snippet record a purchase from the feed targeted to French Canadians:
'items': [
{ 'id': '123456788889',
'price': '19.99',
'quantity': 1
},
{ 'id': '123456755559',
'price': '54.00',
'quantity': 2
}
],
'country': 'ca',
'language': 'fr'
Just make sure to use the ISO two digit country and language codes.