Conviva Web (JavaScript) Sensor Integration

• Conviva Customer Key: As provided by Conviva or your analytics admin.

• App ID: Choose a name for your application (for example, WEB App, LGTV Web App).

• GTM Container: Select an existing container, or create a new container. Select Web as the target platform.

• App Name and Version for the shop (for example, "SFCC Shop" / "1.0.0")

• Conviva Web (JavaScript) Sensor: Get the latest sensor from here.

• Option A: Add template from the GTM's template gallery (recommended)

Open GTM container and navigate to the Templates tab.

• Under Tag Templates, click Search Gallery.

• Search for "Conviva" and select Conviva DPI JS SDK.

• Click Add to add the template to the workspace.

• Option B: Import the template from the GitHub.

Download the template.tpl file from the GitHub repository.

• Open GTM container and navigate to: Templates > Tag Templates > New.

• Click the three-dot menu (...) and select Import.

• Select the downloaded template.tpl file and click Save.

Navigate to Variables -> User-Defined Variables -> New to create the following variables. Use the exact names so that tags can reference them.

• Constant Variables

Conviva -- Customer Key: Your Conviva Customer Key.

• Conviva -- App ID:Application ID, for example, WEB App.

• Conviva -- App Version: Application version, for example a1.0.0/

Data Layer Variables (For each variable, set the version of Data Layer Variable Version to Version 2.)

• General

• Revenue (required)

• Revenue (optional): Create a variable for each optional field you need and map it to the corresponding tag field. Using dedicated fields ensures the template's type validation works correctly (numeric fields are validated as numbers, string fields are validated as non-empty strings).

• Revenue -- Extra Metadata: For any additional fields beyond the ones above, use the Revenue data object (variable) field. This is for extra metadata that does not have a dedicated tag field.

Navigate to Triggers -> New to create following triggers.

• MPA (multi-page app): Use DOM Ready only -- fires as soon as the page structure is ready, before images and heavy resources finish loading.

• SPA or hybrid: Attach both DOM Ready and History Change to the same Page View tag so both the initial load and in-app route changes are tracked.

Navigate to Tags -> New, then select the Conviva DPI JS SDK tag type for each tag below.

Init Tag Ordering and Pre-Init Queue (The behavior depends on which SDK version are using.)

Loads the SDK and initializes tracking. Fire once per page.

• Required Fields

• Optional Fields

• Trigger

Conviva -- Init  (Initialization -- All Pages)

Sends a page-view event. Required for correct session and page metrics.

Trigger

Sends a named custom event with optional data.

If both the table and the variable are set, they are merged. Variable keys take priority.

Trigger

Conviva -- Custom Event  (Custom Event: conviva_customEvent)

dataLayer Push

dataLayer.push({
event: 'conviva_customEvent',
convivaEventName: 'button_click',
convivaEventData: { buttonId: 'cta-hero', section: 'homepage' }
});

Forwarding existing events to Conviva

If your site already pushes events to GA4 or another analytics tool (for example, purchase, add_to_cart, video_play) and you want to forward them to Conviva without adding a separate conviva_customEvent push, use the following approach.

Step 1: Create a Custom JavaScript variable: Conviva -- Current Event Data

This variable reads data directly from the triggering push, bypassing GTM's merged composite state:

function() {
var dl = window.dataLayer || [];
var skip = { 'event': true, 'gtm.uniqueEventId': true, 'gtm.start': true };
for (var i = dl.length - 1; i >= 0; i--) {
var push = dl[i];
if (push && typeof push.event === 'string' && push.event.indexOf('gtm.') !== 0) {
var data = {};
for (var key in push) {
if (!skip[key] && push.hasOwnProperty(key)) data[key] = push[key];
}
return data;
}
}
return {};
}

Step 2: Configure the Conviva Custom Event tag

Step 3 – Choose a trigger strategy

• **Option A:Piggyback on existing triggers **(recommended) Add the Conviva Custom Event tag to your existing GA4/analytics triggers. When GA4 fires on purchase, the Conviva tag fires on the same trigger — {{Event}} returns purchase automatically. No new dataLayer pushes or trigger configurations required.

• Option B:Regex catch-all triggerCreate a new Custom Event trigger, enable Use regex matching, and set the event name to cover all events you want to forward:

purchase|add_to_cart|video_play|checkout_complete

Sends a purchase/revenue event with fixed event name conviva_revenue_event. Enables revenue metrics: Total Revenue, Revenue per Visitor, Average Order Value, Average Cart Size.

Required Fields

Optional Fields

Line-Item Object Keys

Each item in the Purchased items array supports:

productId, name, sku, category, unitPrice, quantity, discount, brand, variant

Trigger

Conviva -- Revenue  (Custom Event: conviva_revenue)

dataLayer Push

dataLayer.push({
event: 'conviva_revenue',
// Required
convivaRevenueOrderAmount: 49.99,
convivaRevenueOrderId: 'ord_12345',
convivaRevenueCurrency: 'USD',
// Optional -- individual fields (type-validated by the template)
convivaRevenueTax: 4.50,
convivaRevenueShipping: 5.99,
convivaRevenueDiscount: 2.00,
convivaRevenueCartSize: 2,
convivaRevenuePaymentMethod: 'card',
convivaRevenuePaymentProvider: 'Stripe',
convivaRevenueOrderStatus: 'completed',
convivaRevenueItems: [
{ productId: 'p1', name: 'Monthly Plan', unitPrice: 24.99, quantity: 1 },
{ productId: 'p2', name: 'Add-on', unitPrice: 19.99, quantity: 1, discount: 1.00 }
],
// Extra metadata -- only for fields without a dedicated tag field
convivaRevenueData: {
couponCode: 'SAVE10',
channel: 'web'
}
});

Sets or updates the viewer/user ID. Fire after login or when user identity is known.

Trigger

Conviva -- Set User ID  (Custom Event: conviva_setUserId)

dataLayer Push

dataLayer.push({
event: 'conviva_setUserId',
convivaUserId: 'user_abc123'
});

Sets global key/value tags applied to all subsequent events.

If both are set, they are merged. Variable keys take priority.

Trigger

Conviva -- Set Custom Tags  (Custom Event: conviva_setCustomTags)

dataLayer Push

dataLayer.push({
event: 'conviva_setCustomTags',
convivaCustomTags: { genre: 'sports', tier: 'premium' }
});

Removes previously set custom tag keys.

Trigger

Conviva -- Unset Custom Tags  (Custom Event: conviva_unsetCustomTags)

dataLayer Push

dataLayer.push({
event: 'conviva_unsetCustomTags',
convivaUnsetTagKeys: 'genre,tier'
});

Reports an error for error-rate analysis.

Trigger

Conviva -- Track Error  (Custom Event: conviva_trackError)

dataLayer Push

dataLayer.push({
event: 'conviva_trackError',
convivaErrorMessage: 'Video playback failed',
convivaErrorFilename: 'player.js'
});

Quick reference for all supported events. Push the event key and data keys in the same dataLayer.push() call.

Main SDK

Cohort Replay SDK

When Init with Cohort Replay is enabled:

Replay always loads before the main SDK. The template handles this automatically.

Customer-Hosted Permissions

The template only allows scripts from sensor.conviva.com by default. If you host scripts on your own domain, you must update the template permissions:

1. In GTM navigate to Templates and open the Conviva DPI JS SDK template.

2. Click the Permissions tab.

3. Under Injects scripts, add your domain (for example, https://cdn.example.com/*).

4. Save the template.

Without this step, GTM blocks the script silently.

Consent Mode

To gate tracking on user consent, assign the Init tag to a consent-based trigger instead of "Initialization -- All Pages". All other Conviva tags depend on Init, so gating Init effectively gates all tracking.

Cross-Subdomain Client ID

Check Enable Client ID in cookies in the Init tag to share clientId across subdomains such as, app.example.com and www.example.com).

Client ID from URL or dataLayer

To sync clientId from another context (for example, a mobile app passing it via URL), create a Custom JavaScript variable named Conviva -- Client ID:

function() {
var q = window.location.search || '';
var match = /[?&]convivaClientId=([^&]*)/.exec(q);
if (match && match[1]) return decodeURIComponent(match[1].replace(/\+/g, ' '));
var dl = window.dataLayer || [];
for (var i = dl.length - 1; i >= 0; i--) {
if (dl[i].convivaClientId) return String(dl[i].convivaClientId).trim();
}
return '';
}

Set the Init tag's Client ID field to {{Conviva -- Client ID}}.

Avoiding Merged Event Data

GTM merges all dataLayer.push() calls into one global state. If you push multiple custom events rapidly, variables may return stale data from a previous push. To always read the most recent push, use Custom JavaScript variables instead of Data Layer Variables for the Custom Event tag:

Conviva -- Custom Event Name (from last push):

function() {
var dl = window.dataLayer || [];
for (var i = dl.length - 1; i >= 0; i--) {
if (dl[i].event === 'conviva_customEvent' && dl[i].convivaEventName)
return dl[i].convivaEventName;
}
return '';
}

Conviva -- Custom Event Data (from last push):

function() {
var dl = window.dataLayer || [];
for (var i = dl.length - 1; i >= 0; i--) {
if (dl[i].event === 'conviva_customEvent' && dl[i].convivaEventData != null)
return dl[i].convivaEventData;
}
return {};
}

Then in your Custom Event tag, set Event name to {{Conviva -- Custom Event Name (from last push)}} and Event data object (variable) to {{Conviva -- Custom Event Data (from last push)}}.

Forwarding Existing Events to Conviva

If your site already pushes events to GA4 or another analytics tool and you want to forward them to Conviva without changing your existing dataLayer pushes, use one Conviva Custom Event tag with GTM's built-in {{Event}} variable — no per-event configuration needed.

Create a Custom JavaScript variable: Conviva -- Current Event Data

function() {
var dl = window.dataLayer || [];
var skip = { 'event': true, 'gtm.uniqueEventId': true, 'gtm.start': true };
for (var i = dl.length - 1; i >= 0; i--) {
var push = dl[i];
if (push && typeof push.event === 'string' && push.event.indexOf('gtm.') !== 0) {
var data = {};
for (var key in push) {
if (!skip[key] && push.hasOwnProperty(key)) data[key] = push[key];
}
return data;
}
}
return {};
}

This variable scans backwards through window.dataLayer, skips GTM internal events (gtm.*), and returns only the keys from the most recent user push — never stale merged data.

Configure the Conviva Custom Event tag:

Trigger options:

Device Metadata

Expand the Device Metadata group in the Init tag to pass device information. All fields are optional.

Tag Sequencing

With SDK v2.0.0 and above, tag sequencing is generally not needed -- the pre-init queue handles timing automatically. However, if you are using v1.5.5, or want explicit ordering for other reasons, use Tag Sequencing:

1. Open the dependent tag: Advanced Settings > Tag Sequencing.

2. Check the Fire a tag before [this tag] fires option and select your Init tag.

• CUSTOMER_KEY as provided by Conviva or your analytics admin.

• App Name and Version for the shop (for example, "SFCC Shop" / "1.0.0")

• Conviva Web (JavaScript) Sensor. Get the latest sensor from here. Download convivaAppTracker.js script file

• Upload the script file into your Salesforce Commerce Cloud's Static folder (for example, /static/conviva/)

Open the Site’s base package htmlHead.isml file (for example, app_storefront_base/cartridge/templates/default/common/htmlHead.isml) and add the following code before any other scripts:

<script>   
(function(p, i) {
if (!p[i]) {
p.GlobalConvivaNamespace = p.GlobalConvivaNamespace || [];
p.GlobalConvivaNamespace.push(i);
p[i] = function() {
(p[i].q = p[i].q || []).push(arguments)
};
p[i].q = p[i].q || [];
}
}(window, "apptracker"));
</script>

In the Site's base package htmlHead.isml file (for example, app_storefront_base/cartridge/templates/default/common/htmlHead.isml), add the following code immediately after the tracker include script:

• appId: App identifier (for example, SFCC Desktop Store)

• convivaCustomerKey: Account Key from Pulse

• appVersion: Semantic version string of the App

Code

// convivaAppTracker -> global namespace for calls   
window.apptracker('convivaAppTracker', 
{     
appId: 'YOUR_SFCC_APP_NAME',     
convivaCustomerKey: 'YOUR_CUSTOMER_KEY',     
appVersion: 'YOUR_APP_VERSION'   
}
); 
</script>

Set the User ID if you have any logged-in customer ID (for example, customer.profile.customerNo) before any auto-collection events:

<script>   
window.apptracker('setUserId', '${customer.profile.customerNo}'); 
</script>

Track page view events after the pages get rendered completely. For Salesforce SPA (Single Page Application) or componentized pages, call the Page View on route/content changes. By default, it uses document.title unless you pass a custom title.

<script>   
// fire when content is ready   
window.apptracker('trackPageView'); 
</script>

Track any custom events (for example, Add to Cart)

<script>   
window.apptracker('trackCustomEvent', {     
name: 'add_to_cart',     
data: {       
productId: '${product.ID}',       
price:     '${product.priceModel.price}'     
}   
}); 
</script>

1. Open your Shopify Online Store.

2. From the menu, navigate Store Dashboard > Sales channels > Online Store > Themes.

3. On the Themes page, click the three dots ellipsis icon next to the Customize button to see the list of available options.

4. Click Edit code.

5. Add the following code to the theme.liquid (layout/theme.liquid) file, before the tag.

Open the theme.liquid file and add the following code with:

• appId: App identifier (for example, My Store Shopify)

• convivaCustomerKey: Account Key from Conviva Pulse

• appVersion: Semantic version string of the App (for example, 1.0.0)

<script>
(function(p, i) {
if (!p[i]) {
p.GlobalConvivaNamespace = p.GlobalConvivaNamespace || [];
p.GlobalConvivaNamespace.push(i);
p[i] = function() {
(p[i].q = p[i].q || []).push(arguments)
};
p[i].q = p[i].q || [];
}
window.apptracker('convivaAppTracker',  {
appId: 'YOUR_STORE_APP_NAME',
convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
appVersion: "YOUR_APP_VERSION"
});
}(window, "apptracker"));
</script>

Set the User ID if you have any logged-in customer ID (for example, ShopifyAnalytics.lib.user().traits().uniqToken).

In the theme.liquid file, add the following script before any auto-collection events:

<script>   

if (ShopifyAnalytics && ShopifyAnalytics.lib && ShopifyAnalytics.lib.user) {
// Make sure the same value can be accessible and used in the pixel side. 
// In this example, we use uniqueToken and event.clientId respectively for 
// Theme and pixel side, as both carries same value.
var userId = ShopifyAnalytics.lib.user().traits().uniqToken;
window.apptracker("setUserId", userId);
}

</script>

1. Open your Shopify Online Store.

2. From the menu, navigate Settings > Customer Events.

3. Click Add or Modify Custom Pixels.

4. Add the convivaAppTracker.js script.

const script = document.createElement('script');
script.setAttribute(src,  “<host_path>/convivaAppTracker.js”);
script.setAttribute('async', '');
document.head.appendChild(script);

Initialize the tracker with the same value of appId, convivaCustomerKey, and appVersion, as specified for Shopify Theme integration.

(function(p, i) {
if (!p[i]) {
p.GlobalConvivaNamespace = p.GlobalConvivaNamespace || [];
p.GlobalConvivaNamespace.push(i);
p[i] = function() {
(p[i].q = p[i].q || []).push(arguments)
};
p[i].q = p[i].q || [];
}
window.apptracker('convivaAppTracker',  {
appId: 'YOUR_STORE_APP_NAME',
convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
appVersion: "YOUR_APP_VERSION",
enableCommonEvents: false, //config to control common events
});
}(window, "apptracker"));

Track page view events after the pages get rendered completely. Subscribe to Shopify’s Pixel Event API to track page view events.

To track the page views, subscribe to the events:

analytics.subscribe('page_viewed', (event) => {
// set the user id, since we use unique Token from Shopify, this event.clientId has same value.
// If a different value is set in theme side, use the same value to set it in pixel side as well.
window.apptracker("setUserId", <Your User ID>); 
window.apptracker('trackPageView');
});

• Subscribe to all standard events:

analytics.subscribe("all_standard_events", trackEcoEvent);
function trackEcoEvent(event) {
if (!window.apptracker) {
return;
}
// Set user ID
window.apptracker("setUserId", <Your User ID>);

// Set tags if any
let tags = {};
window.apptracker('setCustomTags', tags);

// Report event
let eventData = {};

switch (event.name) {
case "page_viewed":
// do nothing if already subscribed
break;
case "ui_extension_errored":
window.apptracker('trackError', {
// track only specific event data
message: event?.data.error.message,
filename: event?.data.error.extensionName,
error: {
stack: event?.data.error.trace
}
});
break;
default:
// track all event data
let eventData = {
...event?.data,
};
window.apptracker('trackCustomEvent', {
name: event?.name,
data: eventData
});
break;
}
}

OR

• Subscribe to the specific events:

analytics.subscribe('checkout_started', (event) => {
window.apptracker("setUserId", <Your User ID>); // set the user id

const checkout = event?.data.checkout;
// send specific details from the event
window.apptracker('trackCustomEvent', {
name: "Checkout Started",
// Send specific event details
data: {
value: checkout.totalPrice.amount,
created_at: event?.timestamp,
order_number: checkout.order.id,
order_id: checkout.order.id
}
});

// OR

// send all event details as data
let eventData = {
...event?.data,
};
window.apptracker('trackCustomEvent', {
name: "Checkout Started",
data: eventData
});
});