Einstein Activities for Hybrid Implementations

With Reports & Dashboards, identify trends over time and make smarter business decisions based on your B2C Commerce data.

Reports & Dashboards analytics can only be derived from either web adapter logs or the Einstein Activities API. By default, SFRA and SiteGenesis analytics data are stored in web adapter logs, while the PWA Kit sends analytics data to Einstein Activities API.

If you are pursuing a Hybrid Implementation Guidance, where some pages are powered by PWA Kit and others are powered by SFRA or SiteGenesis, and you want to use Reports & Dashboards across your entire site, you must update your SFRA or SiteGenesis implementation to use the Einstein Activities API. This ensures that the API captures the full shopper experience, regardless of whether the shopper is in PWA Kit, SFRA, or SiteGenesis.

Only existing customers can access some of the links on this page. Visit Salesforce Commerce Cloud GitHub Repositories and Access for information about how to get access to the repositories.

Tip

This guide shows you how to integrate the Einstein Activities API with SFRA’s checkout, so that it sends the same activities as PWA Kit’s checkout.

If your phased rollout has additional pages on SFRA or SiteGenesis that send analytics data to the web adapter logs, then for those pages follow a process similar to what’s described in this guide. Look at the corresponding pages in the Retail React App and observe which activities they send out. You’ll then need to send the same activities on your SFRA or SiteGenesis pages. As a resource, this overview of Einstein activities shows you where those activities are supposed to be used.

Implementations using SiteGenesis with Composable Storefront aren’t officially supported.

Note

About the Code Examples

Use caution when integrating the code examples provided, and always test your code thoroughly before pushing it to production.

Lines to be added to existing code are marked with the addition (+) symbol and lines to be deleted are marked with the subtraction (-) symbol.

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: $PLACEHOLDER.

Step 1: Update Checkout Controller

Start by updating your checkout controller to include the current basket ID.

1res.render('checkout/checkout', {
2+   basketId: currentBasket.UUID,
3    order: orderModel,
4    customer: accountModel,
5    ...
6});

Step 2: Update Checkout Template

Update the ISML template used for checkout. This change makes the basket ID, items, and total available to the browser.

1-    <div id="checkout-main" class="container data-checkout-stage <isif condition="${pdict.order.usingMultiShipping && pdict.order.shipping.length > 1}">multi-ship</isif>" data-customer-type="${pdict.customer.registeredUser ? 'registered' : 'guest'}" data-checkout-stage="${pdict.currentStage}" data-checkout-get-url="${URLUtils.https('CheckoutServices-Get')}">
2+    <div id="checkout-main" class="container data-checkout-stage <isif condition="${pdict.order.usingMultiShipping && pdict.order.shipping.length > 1}">multi-ship</isif>" data-customer-type="${pdict.customer.registeredUser ? 'registered' : 'guest'}" data-checkout-stage="${pdict.currentStage}" data-checkout-get-url="${URLUtils.https('CheckoutServices-Get')}" data-checkout-price-total="${pdict.order.priceTotal}" data-checkout-items="${JSON.stringify(pdict.order.items)}" data-basket-id="${pdict.basketId}">

Step 3: Create Helpers

Create a JavaScript file called js/einsteinHelpers.js that contains helper functions:

Don’t forget to replace the placeholders $YOUR_SITE_ID and $YOUR_CLIENT_ID with actual values.

Important

1"use strict";
2
3/**
4 * Get the value of a cookie
5 * Source: https://gist.github.com/wpsmith/6cf23551dd140fb72ae7
6 * @param  {string} name  The name of the cookie
7 * @return {string | undefined}       The cookie value
8 */
9function getCookie(name) {
10  var value = "; " + document.cookie;
11  var parts = value.split("; " + name + "=");
12  var result;
13
14  if (parts.length === 2) {
15    result = parts.pop().split(";").shift();
16  }
17  return result;
18}
19
20/**
21 * Fire a given Einstein activity with the provided data.
22 *
23 * @param {string} name - The name of the activity.
24 * @param {Object} data - The activity payload.
25 */
26function fireEinsteinActivity(name, data) {
27  // NOTE: These should be placed in the custom preferences of BM. This will help
28  // avoid any code deployments if you need to change these values.
29  // NOTE 2: this is _Einstein_ site id (not the same as SFRA one like RefArch).
30  var SITE_ID = "$YOUR_SITE_ID";
31  var CLIENT_ID = "$YOUR_CLIENT_ID";
32  // Reports & Dashboards will only show data that's been tagged as `prd` (production)
33  var INSTANCE_TYPE = "prd";
34
35  // Assign the realm to the data.
36  var activityData = Object.assign(data, {
37    realm: SITE_ID.split("-")[0],
38    instanceType: INSTANCE_TYPE,
39  });
40
41  var userId = data.userId;
42  var cookieId = data.cookieId;
43
44  // Apply payload information for logged in users.
45  if (userId) {
46    activityData = Object.assign(activityData, {
47      userId: userId,
48    });
49  }
50
51  if (cookieId) {
52    activityData = Object.assign(activityData, {
53      cookieId: cookieId,
54    });
55  }
56
57  var url = "https://api.cquotient.com/v3/activities" + "/" + SITE_ID + "/" + name;
58
59  try {
60    fetch(url, {
61      headers: {
62        "Content-Type": "application/json",
63        "x-cq-client-id": CLIENT_ID,
64      },
65      method: "POST",
66      body: JSON.stringify(activityData),
67    });
68  } catch (e) {
69    console.error(e);
70  }
71}
72
73var exports = {
74  fireEinsteinActivity: fireEinsteinActivity,
75  getCookie: getCookie,
76};
77
78module.exports = exports;

Step 4: Record Activities

Update your checkout.js script to record activities. You must add this call to require() at the top of your checkout script, and it must appear after any existing imports.

1var einsteinHelpers = require('../einsteinHelpers');

Trigger the checkoutStep activity when the checkout stage is changed. Append the following code to the updateUrl method:

1/**
2 * @returns {boolean} whether the current customer is registered or not
3 */
4function isRegisteredCustomer() {
5  return $(".data-checkout-stage").data("customer-type") === "registered";
6}
7
8/**
9 * Get the cookieId, which is a unique identifier used for linking subsequent activities to the same user.
10 * If the cookieId is not defined, then Reports & Dashboards will treat the activity as coming from an anonymous user.
11 * @returns {string | undefined} value of the cookieId param for Einstein Activities API
12 */
13function getCookieId() {
14  var siteId = window.CQuotient && window.CQuotient.siteId;
15  // This usid cookie is set by either PWA or plugin_slas
16  return (
17    einsteinHelpers.getCookie("usid_" + siteId) || einsteinHelpers.getCookie("usid") || undefined
18  );
19}
20
21/**
22 * Get the userId, which is for linking registered users across different devices.
23 * @returns {string | undefined} value of the userId param for Einstein Activities API
24 */
25function getUserId() {
26  var siteId = window.CQuotient && window.CQuotient.siteId;
27  // This enc_user_id is set by PWA
28  return (
29    window.localStorage.getItem("enc_user_id_" + siteId) ||
30    window.localStorage.getItem("enc_user_id") ||
31    undefined
32  );
33}
34
35/**
36 * Updates the URL to determine stage
37 * @param {number} currentStage - The current stage the user is currently on in the checkout
38 */
39function updateUrl(currentStage) {
40  // ...
41
42  var cookieId = getCookieId();
43  var userId = isRegisteredCustomer() ? getUserId() : undefined;
44
45  einsteinHelpers.fireEinsteinActivity("checkoutStep", {
46    basketId: $("#checkout-main").data("basket-id"),
47    stepName: checkoutStages[currentStage],
48    stepNumber: currentStage,
49    cookieId: cookieId,
50    userId: userId,
51  });
52}

Triggering the checkoutStep activity in the updateUrl method ensures that any transition from one checkout stage to the next (or previous) is tracked.

Note

Trigger the beginCheckout activity at the end of the initialize function for your checkout code:

1//
2// Send Einstein `beginCheckout` activity
3//
4// Parse total amount value
5var amount = $("#checkout-main").data("checkout-price-total");
6amount = Number(amount.replace(/[^0-9.-]+/g, ""));
7
8var products = $("#checkout-main")
9  .data("checkout-items")
10  .items.map(function (item) {
11    return {
12      id: item.id,
13      price: Number(item.priceTotal.price.replace(/[^0-9.-]+/g, "")),
14      quantity: item.quantity,
15    };
16  });
17
18var cookieId = getCookieId();
19var userId = isRegisteredCustomer() ? getUserId() : undefined;
20
21einsteinHelpers.fireEinsteinActivity("beginCheckout", {
22  products: products,
23  amount: amount,
24  cookieId: cookieId,
25  userId: userId,
26});

The beginCheckout activity is only triggered one time per page load during checkout. Activity data preparation is handled automatically.

Note

That’s it! You’ve successfully integrated Einstein Activities with SFRA’s checkout. To finish your setup of Reports & Dashboards, complete the steps in Reports & Dashboards.

Einstein Activities for Hybrid Implementations

About the Code Examples

Step 1: Update Checkout Controller

Step 2: Update Checkout Template

Step 3: Create Helpers

Step 4: Record Activities

See Also