# CJ Universal Tag Integration Guide

## Overview
This document provides the technical requirements for integrating with CJ's Universal Tag Solution. This integration allows you to rely on CJ to take on the work of maintaining tracking integrity when browser and regulatory changes are implemented. CJ's Universal Tag Solution enables you to take advantage of the continuous improvements CJ makes to our tracking technology, without having to make integration changes to your website.


###### CJ’s Universal Tag Solution contains two components:
1. A Server Side cookie
<br>&nbsp; &nbsp; <i>Note: A CJ Client Integration Engineer will provide additional instruction specific to your sites tracking needs.</i></br>
2. A website tag for all pages of your site

## Integration Details
To receive the full benefits of this integration, a server side cookie is required to be configured.  

## GDPR Compliance
#### Accepting the cjdata URL parameter
As part of CJ's compliance with the GDPR, we will pass a URL parameter on the Advertiser's landing page called "cjdata". This parameter will be used to pass through information regarding GDPR consent, so the Universal Tag can behave in compliance with the regulation. Please ensure you can accept this URL parameter on all landing pages where an affiliate may drive traffic to your website.

Example landing page:
https://www.advertiser.com?cjdata=mx87hgm


## CJ Tag Script
The CJ Tag script is required on all site pages, including your order confirmation page. This should be at the end of your HTML pages, before the closing \</BODY> tag. Your TAG_ID will be provided to you by a member of CJ's Client Integration team.

```HTML
<!-- BEGIN CJ TRACKING CODE - DO NOT MODIFY -->
<script type="text/javascript">
(function(a,b,c,d){
a='https://www.mczbf.com/tags/<TAG_ID>/tag.js';
b=document;c='script';d=b.createElement(c);d.src=a;
d.type='text/java'+c;d.async=true;
d.id='cjapitag';
a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a)
})();
</script>
<!-- END CJ TRACKING CODE -->
```


## Tag for Site Pages
This section contains example code for your Site Page Tag that will go on all pages of your site that are not transaction confirmation or purchase confirmation pages. This section also contains the list of required and optional parameters you can send in your Site Page Tag.

Important notes for configuring your Site Page Tag:

* Place the site tag data near the top of the page, within the opening and closing \ tags with no visible line breaks.
* The site tag data should be placed <b><i>before</b></i> the CJ Tag Script.
* These coding examples are provided as a courtesy and for your reference only. These examples may not work for your specific shopping cart or web site. CJ does not guarantee the accuracy of these coding examples.
* Placeholders with brackets denote the location of required values. Brackets are for illustration purposes only, and should NOT be placed in the actual code.
* The <b>enterpriseId</b> value will be provided to you by a member of CJ’s Client Integration team.
* A member of CJ’s Client Integration team will verify the accuracy of your conversion tag configuration.

### Example Site Page Tag
```HTML
<!-- BEGIN CJ TRACKING CODE -->

<script type='text/javascript'>
if (!window.cj) window.cj = {};

cj.sitePage = {
    enterpriseId: <CID>,
    pageType: '<SEE PAGE TYPE TABLE BELOW>',
    userId: '<userId>',
    referringChannel: '<referringChannel>',
    cartSubtotal: <cartSubtotal>,
    items: [
        { 'unitPrice': 9.99, 'itemId': 'M223-02-001', 'quantity': 20, 'discount': 0 },
        { 'unitPrice': 24.99, 'itemId': 'B00138CTNY', 'quantity': 4, 'discount': 1.00 },
        { 'unitPrice': 1449.00, 'itemId': 'MWHA2LL/A', 'quantity': 1, 'discount': 350.00 },
    ]
};
</script>

<script type="text/javascript">
(function(a,b,c,d){
a='//www.mczbf.com/tags/<TAG_ID>/tag.js';
b=document;c='script';d=b.createElement(c);d.src=a;
d.type='text/java'+c;d.async=true;
d.id='cjapitag';
a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a)
})();
</script>

<!-- END CJ TRACKING CODE -->
```

### Site Page Tag Parameters
| Parameter | Type | Description
|:-----|:-----|:-----|
| enterpriseId | Id | This value is set to your CJ Enterprise ID, which is a static value provided by CJ.
| pageType | [PageType](#page_type_accepted_values) | See [PageType](#page_type_accepted_values) table below for a list of accepted values
| userId | string | Unique user ID you have assigned to the customer (i.e. membership ID, customer ID). This should not contain any Personally Identifiable Information
| referringChannel | See list of expected values | Marketing channel the user was referred by before arriving to your site. This value only needs to be populated on the landing page where the user first arrives to your site. <br> Expected values: <br> <ul> <li>Affiliate<li>Display<li>Social<li>Search<li>Email<li>Direct_Navigation
| cartSubtotal | Decimal | Subtotal of the shopping cart. This should only be populate when the user is on a shopping cart page. This should not include taxes or shipping costs.
| items |  | Include all items in the shopping cart. This should only be populate when the user is on a shopping cart page. This should not include taxes or shipping costs. <br><ul><li><b>itemId</b><ul><li> Identifier for the item purchased</ul><br>Requirements:<ul><li> A maximum of 100 sets of item-based values is supported for each order <li>The system supports an alphanumeric string with dashes or underscores only. Spaces and other characters are not permitted. <li> Item SKU values must be less than or equal to 100 characters.<li>Example: item.product.itemId=3214Sku</ul></ul><br><ul><li><b>unitPrice</b><ul><li>Amount parameter that corresponds to each individual item in the transaction. For example, a typical sale-related action would provide an unitPrice parameter equal to that of the SKU's Unit Price (amount of one of that item). Do not adjust the amount when the quantity is greater than one (e.g. do not provide unitPrice=6.00 for two items at 3.00 each—see quantity below).</ul><br> Requirements: <ul><li> The corresponding value (e.g., 13.49) must be in the format of numbers, and may have a decimal point. No other characters, such as dollar signs ("$") or commas (","), are supported by the CJ system. <li> A  maximum of 100 sets of item-based values is supported for each order. <li> If the currency parameter is omitted from the tag or if the value is empty, products default to the advertiser's functional currency.  <br> The system assumes the unitPrice value is in the currency specified in the currency parameter. If the advertiser specifies a currency other than the functional currency, the system converts the unitPrice value to an amount in the functional currency using a current conversion rate. <li>Example: item.unitPrice=13.49</ul></ul><br><ul><li><b>quantity</b><ul><li> Quantity parameter that corresponds to each item in the transaction. The quantity value is multiplied by the unitPrice value to determine the total for a given item (e.g. quantity 2 of unitPrice 3.00 would result in 6.00 being recorded in our system).</ul><br> Requirements: <ul> <li> A maximum of 100 sets of item-based values is supported for each order. <li> The qtyx field does not recognize decimal amounts. For example, quantity=1.0 is read by the system as quantity=10.<li>Example: item.quantity=2<br></ul></ul><ul><li><b>discount</b><ul><li> Optional discount parameter that corresponds to each itemId in the transaction. The discount value represents the discount applied for the associated item.<br><li>The item level discount amount is spread across all items in the series, which gives you the new individual item amount. That new amount is then multiplied by the quantity to get the subtotal for that item. (unitPrice -(discount/quantity)) * quantity). <br> <br> For example, if unitPrice=10, quantity=2 and discount=5 the new amount for each item is 7.50 and the subtotal for the item would be 15.00. | item.discount=5.55 | No|


### Page Type Accepted Values
This section contains the accepted values for the pageType parameter in the Site Page Tag and Conversion Tag. This list is organized by business vertical

#### Vertical Parameters
| Page Type |Advertiser Vertical| Notes
|:-----|:-----|:-----
|accountCenter|All Verticals|Any pages within the account center after the user has logged in
|accountSignup|All Verticals|
|applicationStart|Finance Only|
|branchLocator|Finance Only|
|cart|Retail, Network Services, and Travel Only|Pass all items in the cart, if possible. Follow the format outlines in the Site Tag code example|
|category|Retail, Network Services, and Finance Only|
|conversionConfirmation|All Verticals|
|department|Retail, Network Services, and Finance Only|
|homepage|All Verticals|
|information|Travel Only|
|productDetail|Retail, Network Services, and Finance Only|
|propertyDetail|Travel Only|
|propertyResults|Travel Only|
|searchResults|All Verticals
|storeLocator|Retail and Network Services Only|
|subCategory|Retail, Network Services, and Finance Only|




## Conversion Tag Configuration

This section contains example code for your CJ Conversion Tag that will report transactions that occur on your website to CJ. This section also contains the list of required and optional parameters you can send in your conversion tag.

Important notes for configuring your CJ Conversion Tag:
* Place the conversion tag data near the top of your Thank You or confirmation following the order or application process, within the opening and closing \<BODY> tags with no visible line breaks.
* The conversion tag data should be placed ***before*** the CJ Tag script.
* These coding examples are provided as a courtesy and for your reference only. These examples may not work for your specific shopping cart or web site. CJ does not guarantee the accuracy of these coding examples.
* Placeholders with brackets denote the location of required values. Brackets are for illustration purposes only, and should NOT be placed in the actual code.
* The **enterpriseId** and **actionTrackerId** values will be provided to you by a member of CJ’s Client Integration team.
* A member of CJ’s Client Integration team will verify the accuracy of your conversion tag configuration.



### Example Order - Single Action
```HTML
<!-- BEGIN CJ TRACKING CODE -->

<script type='text/javascript'>
if (!window.cj) window.cj = {};

cj.order = {
    enterpriseId: <CID>, // required
    pageType: 'conversionConfirmation',
    userId: '<userId>',
    orderId: '<ORDER_ID>', // required
    actionTrackerId: <ACTION_ID>, // required
    currency: '<CURRENCY>', // required
    amount: <AMOUNT>,
    discount: <DISCOUNT>,
    coupon: '<COUPON>',
    cjeventOrder: '<cje_cookie_value>', //required whenever advertiser uses their own cookie to store the Event ID
    items: [
        { 'unitPrice': 9.99, 'itemId': 'M223-02-001', 'quantity': 20, 'discount': 0 },
        { 'unitPrice': 24.99, 'itemId': 'B00138CTNY', 'quantity': 4, 'discount': 1.00 },
        { 'unitPrice': 1449.00, 'itemId': 'MWHA2LL/A', 'quantity': 1, 'discount': 350.00 },
    ]
};
</script>

<script type="text/javascript">
(function(a,b,c,d){
a='//www.mczbf.com/tags/<TAG_ID>/tag.js';
b=document;c='script';d=b.createElement(c);d.src=a;
d.type='text/java'+c;d.async=true;
d.id='cjapitag';
a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a)
})();
</script>

<!-- END CJ TRACKING CODE -->
```

### Example Order - Multiple Action
* The cj.orders data object should be used for any advertiser that needs to fire multiple actions for the same transaction
* cj.orders accepts an array of orders than can include different CIDs and Actions IDs

```HTML
<!-- BEGIN CJ TRACKING CODE -->

<script type='text/javascript'>
if (!window.cj) window.cj = {};

cj.orders = [{
    enterpriseId: <CID>, // required
    pageType: 'conversionConfirmation',
    userId: '<userId>',
    orderId: '<ORDER_ID>', // required
    actionTrackerId: <ACTION_ID>, // required
    currency: '<CURRENCY>', // required
    amount: <AMOUNT>,
    discount: <DISCOUNT>,
    coupon: '<COUPON>',
    cjeventOrder: '<cje_cookie_value>', //required whenever advertiser uses their own cookie to store the Event ID
    items: [
        { 'unitPrice': 9.99, 'itemId': 'M223-02-001', 'quantity': 20, 'discount': 0 },
        { 'unitPrice': 24.99, 'itemId': 'B00138CTNY', 'quantity': 4, 'discount': 1.00 },
        { 'unitPrice': 1449.00, 'itemId': 'MWHA2LL/A', 'quantity': 1, 'discount': 350.00 },
    ]
},
{
    enterpriseId: <CID>, // required
    pageType: 'conversionConfirmation',
    userId: '<userId>',
    orderId: '<ORDER_ID>', // required
    actionTrackerId: <ACTION_ID>, // required
    currency: '<CURRENCY>', // required
    amount: <AMOUNT>,
    discount: <DISCOUNT>,
    coupon: '<COUPON>',
    cjeventOrder: '<cje_cookie_value>', //required whenever advertiser uses their own cookie to store the Event ID
    items: [
        { 'unitPrice': 9.99, 'itemId': 'M223-02-001', 'quantity': 20, 'discount': 0 },
        { 'unitPrice': 24.99, 'itemId': 'B00138CTNY', 'quantity': 4, 'discount': 1.00 },
        { 'unitPrice': 1449.00, 'itemId': 'MWHA2LL/A', 'quantity': 1, 'discount': 350.00 },
    ]
}];
</script>

<script type="text/javascript">
(function(a,b,c,d){
a='//www.mczbf.com/tags/<TAG_ID>/tag.js';
b=document;c='script';d=b.createElement(c);d.src=a;
d.type='text/java'+c;d.async=true;
d.id='cjapitag';
a=b.getElementsByTagName(c)[0];a.parentNode.insertBefore(d,a)
})();
</script>

<!-- END CJ TRACKING CODE -->
```

### Conversion Tag Parameters - Order Level

| Parameter | Type | Description | Required
|:-----|:-----|:-----|:-----|
| actionTrackerId | Id | This is a static value provided by CJ. Each account may have multiple actions and each will be referenced by a different actionTrackerId value.| Yes
| userId | string | Unique user ID you have assigned to the customer (i.e. membership ID, customer ID). This should not contain any Personally Identifiable Information | Optional
| amount | Decimal | The system assumes the amount value is in the currency specified in the currency parameter. If you specify a currency other than your functional currency, the system converts the amount value to an amount in your functional currency using a current conversion rate. The amount value should not include shipping or tax.| Yes  
| coupon | String | The coupon/voucher code used in the transaction | No
| currency | String | Identifies the currency used to determine the amount value for the order. This three-letter code is static and can be hard-coded into the URL call for the image.  If a code is not specified, product prices display in the advertiser’s functional currency. If a blank value is submitted (“cj.order.currency”, with no specified value), a transaction error will occur. <br> <br> For a list of supported currencies and codes, please visit the Support Center.| Yes
| discount | Decimal | Discount associated with the order in original currency | Yes
| enterpriseId | Id | This value is set to your CJ Enterprise ID, which is a static value provided by CJ.| Yes
| orderId | Id | The orderId is a unique identifier, such as an order identifier or invoice number, which must be populated for each order. It is used to reconcile orders in the advertiser's system with CJ in order to validate each sale or lead.  <br> <ul> <li> This value will be truncated after the 96th character  <li> Only alphanumeric characters, dashes, and underscores can be included in the orderId field  <li> CJ prohibits the submission of personally identifiable information in the orderId field, such as a full or partial email address| Yes
|PageType|[PageType](#page_type_accepted_values)|||
|cjeventOrder|string|contains the CJ Event ID value from the "cje" cookie created by the advertiser to store the Event ID|Required


### Conversion Tag Parameters - Item Level

Your CJ Client Integration Engineer will instruct you on when to use these parameters


| Parameter | Description | Required
|:-----|:-----|:-----|
| itemId | Identifier for the item purchased <br> <br>Additional Requirements:  <ul> <li> A maximum of 100 sets of item-based values is supported for each order <li>The system supports an alphanumeric string with dashes or underscores only. Spaces and other characters are not permitted. <li> Item SKU values must be less than or equal to 100 characters.| Yes, for item-based actions
| unitPrice |  Amount parameter that corresponds to each individual item in the transaction. For example, a typical sale-related action would provide an unitPrice parameter equal to that of the SKU's Unit Price (amount of one of that item). Do not adjust the amount when the quantity is greater than one (e.g. do not provide unitPrice=6.00 for two items at 3.00 each—see quantity below).  <br> <br> Requirements: <ul>  <li> The corresponding value (e.g., 13.49) must be in the format of numbers, and may have a decimal point. No other characters, such as dollar signs ("$") or commas (","), are supported by the CJ system. <li> A  maximum of 100 sets of item-based values is supported for each order. <li> If the currency parameter is omitted from the tag or if the value is empty, products default to the advertiser's functional currency.  <br> The system assumes the unitPrice value is in the currency specified in the currency parameter. If the advertiser specifies a currency other than the functional currency, the system converts the unitPrice value to an amount in the functional currency using a current conversion rate.| Yes, for item-based actions
| quantity |  Quantity parameter that corresponds to each item in the transaction. The quantity value is multiplied by the unitPrice value to determine the total for a given item (e.g. quantity 2 of unitPrice 3.00 would result in 6.00 being recorded in our system).  <br> <br> Requirements: <ul> <li> A maximum of 100 sets of item-based values is supported for each order. <li> The qtyx field does not recognize decimal amounts. For example, quantity=1.0 is read by the system as quantity=10. | Yes, for item-based actions|                                                                    
| discount | Optional discount parameter that corresponds to each itemId in the transaction. The discount value represents the discount applied for the associated item. <br><br> The item level discount amount is spread across all items in the series, which gives you the new individual item amount. That new amount is then multiplied by the quantity to get the subtotal for that item. (unitPrice -(discount/quantity)) * quantity). <br> <br> For example, if unitPrice=10, quantity=2 and discount=5 the new amount for each item is 7.50 and the subtotal for the item would be 15.00.| No|