DocumentationExperience PlatformMigrate Target from at.js 2.x to Web SDK

Send parameters to Target using Platform Web SDK

Last update: Thu Oct 03 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Intermediate
  • Experienced
  • Developer

Target implementations differ across websites due to site architecture, business requirements, and features used. Most Target implementations include passing various parameters for contextual information, audiences, and content recommendations.

Let’s use a simple product details page and an order confirmation page to demonstrate the differences between the libraries when passing parameters to Target.

Assume the following two example pages using at.js:

at.js on a Product Details page:
code language-html 
<!doctype html>
<html>
<head>
  <title>Product Details - Men's Shirt</title>
  <!--Target parameters -->
  <script>
    targetPageParams = function() {
      return {
        // Property token
        "at_property": "5a0fd9bb-67de-4b5a-0fd7-9cc09f50a58d",
        // Mbox parameters
        "pageName": "product detail",
        // Profile parameters
        "profile.gender": "male",
        "user.categoryId": "clothing",
        // Entity parameters for Target Recomendations
        "entity.id": "SKU-00001-LARGE",
        "entity.categoryId": "clothing,shirts",
        "entity.customEntity": "some value",
        "cartIds": "SKU-00002,SKU-00003",
        "excludedIds": "SKU-00001-SMALL",
        // Customer ID for cross-device profile synching and Customer Attributes
        "mbox3rdPartyId": "TT8675309",
      };
    };
  </script>
  <!--Target at.js library loaded asynchonously-->
  <script src="/libraries/at.js" async></script>
</head>
<body>
  <h1 id="title">Men's Large Shirt</h1>
  <p>SKU: SKU-00001-LARGE</p>
</body>
</html>
at.js on an Order Confirmation page:
code language-html 
<!doctype html>
<html>
<head>
  <title>Order Confirmation</title>-->
  <!--Target parameters -->
  <script>
    targetPageParams = function() {
      return {
        // Property token
        "at_property": "5a0fd9bb-67de-4b5a-0fd7-9cc09f50a58d",
        // Order confirmation parameters
        "orderId": "ABC123",
        "productPurchasedId": "SKU-00002,SKU-00003",
        "orderTotal": 1337.89,
        // Customer ID for cross-device profile synching and Customer Attributes
        "mbox3rdPartyId": "TT8675309",
      };
    };
  </script>
  <!--Target at.js library loaded asynchonously-->
  <script src="/libraries/at.js" async></script>
</head>
<body>
  <h1 id="title">Order Confirmation</h1>
  <p>Thank you for your order</p>
</body>
</html>

Parameter-mapping summary

The Target parameters for these pages are sent differently using the Platform Web SDK. There are multiple ways to pass parameters to Target using at.js:

  • Set with targetPageParams() function for the page load event (used in the examples on this page)
  • Set with targetPageParamsAll() function for all Target requests on the page
  • Send parameters directly with the getOffer() function for a single location
  • Send parameters directly with the getOffers() function for one or more locations

The Platform Web SDK provides a single consistent way to send data without the need for extra functions. All parameters must be passed in the payload with the sendEvent command and fall under two categories:

  • Automatically mapped from the xdm object
  • Manually passed using the data.__adobe.target object

The table below outlines how the example parameters would be remapped using Platform Web SDK:

Example at.js parameter
Platform Web SDK option
Notes
at_property
N/A
Property tokens are configured in the datastream and cannot be set in the sendEvent call.
pageName
xdm.web.webPageDetails.name
All Target mbox parameters must be passed as part of the xdm object and conform to a schema using the XDM ExperienceEvent class. Mbox parameters cannot be passed as part of the data object.
profile.gender
data.__adobe.target.profile.gender
All Target profile parameters must be passed as part of the data object and prefixed with profile. to be mapped appropriately.
user.categoryId
data.__adobe.target.user.categoryId
Reserved parameter used for Target’s Category Affinity feature which must be passed as part of the data object.
entity.id
data.__adobe.target.entity.id
OR
xdm.productListItems[0].SKU
Entity IDs are used for Target Recommendations behavioral counters. These entity IDs can either be passed as part of the data object or automatically mapped from the first item in the xdm.productListItems array if your implementation uses that field group.
entity.categoryId
data.__adobe.target.entity.categoryId
Entity category IDs can be passed as part of the data object.
entity.customEntity
data.__adobe.target.entity.customEntity
Custom entity parameters are used for updating the Recommendations product catalog. These custom parameters must be passed as part of the data object.
cartIds
data.__adobe.target.cartIds
Used for Target’s cart-based recommendations algorithms.
excludedIds
data.__adobe.target.excludedIds
Used to prevent specific entity IDs from returning in a recommendations design.
mbox3rdPartyId
Set in the xdm.identityMap object
Used for synching Target profiles across devices and Customer Attributes. The namespace to use for the customer ID must be specified in the Target configuration of the datastream.
orderId
xdm.commerce.order.purchaseID
Used for identifying a unique order for Target conversion tracking.
orderTotal
xdm.commerce.order.priceTotal
Used for tracking order totals for Target conversion and optimization goals.
productPurchasedId
data.__adobe.target.productPurchasedId
OR
xdm.productListItems[0-n].SKU
Used for Target conversion tracking and recommendations algorithms. Refer to the entity parameters section below for details.
mboxPageValue
data.__adobe.target.mboxPageValue
Used for the custom scoring activity goal.

Custom parameters

Custom mbox parameters must be passed as XDM data with the sendEvent command. It is important to ensure that the XDM schema includes all fields required for your Target implementation.

at.js example using targetPageParams():

targetPageParams = function() {
  return {
    "pageName": "product detail"
  };
};

Platform Web SDK JavaScript examples using sendEvent command:

JavaScript
code language-javascript 
alloy("sendEvent", {
  "xdm": {
    "web": {
      "webPageDetails": {
        // Other attributes included according to xdm schema
        "name": "product detail"
      }
    }
  }
});
Tags

In tags, first use an XDM object data element to map to the XDM field:

Mapping to an XDM field in an XDM Object data element {modal="regular"}

And then include your XDM object in your Send event action (multiple XDM objects can be merged):

Including an XDM object data element in a Send event {modal="regular"}

NOTE
Because custom mbox parameters are part of xdm object you need to update any audiences, activities, or profile scripts that reference these mbox parameters using their new names. See the Update Target audiences and profile scripts for Platform Web SDK compatibility page of this tutorial for more information.

Profile parameters

Target profile parameters must be passed under the data.__adobe.target object in the Platform Web SDK sendEvent command payload.

Similar to at.js, all profile parameters must also be prefixed with profile. for the value to be properly stored as a persistent Target profile attribute. The reserved user.categoryId parameter for Target’s Category Affinity capability is prefixed with user..

at.js example using targetPageParams():

targetPageParams = function() {
  return {
    "profile.gender": "male",
    "user.categoryId": "clothing"
  };
};

Platform Web SDK examples using sendEvent command:

JavaScript
code language-javascript 
alloy("sendEvent", {
  "data": {
    "__adobe": {
      "target": {
        "profile.gender": "male",
        "user.categoryId": "clothing"
      }
    }
  }
});
Tags

In tags, first create a data element to define the data.__adobe.target object:

Defining your data object in a data element {modal="regular"}

And then include your data object in your Send event action (multiple objects can be merged):

Including a data object in a Send event {modal="regular"}

Entity parameters

Entity parameters are used to pass behavioral data and supplemental catalog information for Target Recommendations. All entity parameters supported by at.js are also supported by the Platform Web SDK. Similar to profile parameters, all entity parameters should be passed under the data.__adobe.target object in the Platform Web SDK sendEvent command payload.

Entity parameters for a specific item must be prefixed with entity. for proper data capture. The reserved cartIds and excludedIds parameters for recommendations algorithms should not be prefixed and the value for each must contain a comma-separated list of entity IDs.

at.js example using targetPageParams():

targetPageParams = function() {
  return {
    "entity.id": "SKU-00001-LARGE",
    "entity.categoryId": "clothing,shirts",
    "entity.customEntity": "some value",
    "cartIds": "SKU-00002,SKU-00003",
    "excludedIds": "SKU-00001-SMALL"
  };
};

Platform Web SDK examples using sendEvent command:

JavaScript
code language-javascript 
alloy("sendEvent", {
  "data": {
    "__adobe": {
      "target": {
        "entity.id": "SKU-00001-LARGE",
        "entity.categoryId": "clothing,shirts",
        "entity.customEntity": "some value",
        "cartIds": "SKU-00002,SKU-00003",
        "excludedIds": "SKU-00001-SMALL"
      }
    }
  }
});
Tags

In tags, first create a data element to define the data.__adobe.target object:

Defining your data object in a data element {modal="regular"}

And then include your data object in your Send event action (multiple objects can be merged):

Including a data object in a Send event {modal="regular"}

NOTE
If the commerce field group is used and the productListItems array is included in the XDM payload, then the first SKU value in this array is mapped to entity.id for the purposes of incrementing a product view.

Purchase parameters

Purchase parameters are passed on an order confirmation page after a successful order and are used for Target conversion and optimization goals. With a Platform Web SDK implementation, these parameters and are automatically mapped from XDM data passed as part of the commerce field group.

at.js example using targetPageParams():

targetPageParams = function() {
  return {
    "orderId": "ABC123",
    "productPurchasedId": "SKU-00002,SKU-00003"
    "orderTotal": 1337.89
  };
};

Purchase information is passed to Target when the commerce field group has purchases.value set to 1. The order ID and order total are automatically mapped from the order object. If the productListItems array is present, then the SKU values are use for productPurchasedId.

Platform Web SDK examples using sendEvent command:

JavaScript
code language-javascript 
alloy("sendEvent", {
  "xdm": {
    "commerce": {
      "order": {
        "purchaseID": "ABC123",
        "priceTotal": 1337.89
      },
      "purchases": {
        "value": 1
      }
    },
    "productListItems": [{
      "SKU": "SKU-00002"
    }, {
      "SKU": "SKU-00003"
    }]
  }
});
Tags

In tags, first use an XDM object data element to map to the XDM fields:

Mapping to an XDM field in an XDM Object data element {modal="regular"}

And then include your XDM object in your Send event action (multiple XDM objects can be merged):

Including an XDM object data element in a Send event {modal="regular"}

NOTE
The productPurchasedId value can also be passed as a comma-separated list of entity IDs under the data object.

Customer Id (mbox3rdPartyId)

Target allows profile synching across devices and systems using a single customer Id. With at.js, this could be set as the mbox3rdPartyId in the Target request or as the first customer id sent to the Experience Cloud Identity Service. Unlike with at.js, a Platform Web SDK implementation allows you to specify which customer ID to use as the mbox3rdPartyId if there are multiple. For example, if your business has a global customer ID and separate customer IDs for different lines of business, you can configure which ID Target should use.

There are a few steps to set up ID synching for Target cross-device and Customer Attributes use cases:

  1. Create an identity namespace for the customer ID in Identities screen of Data Collection or Platform
  2. Make sure that the alias in Customer Attributes matches the identity symbol of your namespace
  3. Specify the identy symbol as the Target Third Party ID Namespace in the Target configuration of the datastream
  4. Execute a sendEvent command using the identityMap field group

at.js example using targetPageParams():

targetPageParams = function() {
  return {
    "mbox3rdPartyId": "TT8675309"
  };
};

Platform Web SDK examples using sendEvent command:

JavaScript
code language-javascript 
alloy("sendEvent", {
  "xdm": {
    "identityMap": {
      "GLOBAL_CUSTOMER_ID": [{
        "id": "TT8675309",
        "authenticatedState": "authenticated"
      }]
    }
  }
});
Tags

The ID value, Authenticated state and Namespace are captured in an Identity map data element:
Identity Map data element capturing the customer id {modal="regular"}

The Identity map data element is then used to set the identityMap field in the XDM object data element:
Identity Map data element used in XDM object data element {modal="regular"}

The XDM object is then included in the Send event action of a rule:

Including an XDM object data element in a Send event {modal="regular"}

In your datastream’s Adobe Target service, be sure to set the Target Third Party ID Namespace to the same namespace used in the Identity map data element:
Set the Target Third Party ID Namespace in the datastream {modal="regular"}

Platform Web SDK example

Now that you understand how the different Target parameters are mapped using the Platform Web SDK, our two example pages could be migrated from at.js to the Platform Web SDK as shown below. The example pages include the following:

  • Target prehiding snippet for an asynchronous library implementation
  • The Platform Web SDK base code
  • The Platform Web SDK JavaScript library
  • A configure command to initialize the library
  • A sendEvent command to send data and request Target content to be rendered
Web SDK on a Product Details page:
code language-html 
<!doctype html>
<html>
<head>
  <title>Product Details - Men's Shirt</title>

  <!--Prehiding snippet for Target with asynchronous Web SDK deployment-->
  <script>
    !function(e,a,n,t){var i=e.head;if(i){
    if (a) return;
    var o=e.createElement("style");
    o.id="alloy-prehiding",o.innerText=n,i.appendChild(o),setTimeout(function(){o.parentNode&&o.parentNode.removeChild(o)},t)}}
    (document, document.location.href.indexOf("mboxEdit") !== -1, ".body { opacity: 0 !important }", 3000);
  </script>

  <!--Platform Web SDK base code-->
  <script>
    !function(n,o){o.forEach(function(o){n[o]||((n.__alloyNS=n.__alloyNS||
    []).push(o),n[o]=function(){var u=arguments;return new Promise(
    function(i,l){n[o].q.push([i,l,u])})},n[o].q=[])})}
    (window,["alloy"]);
  </script>

  <!--Platform Web SDK loaded asynchonously. Change the src to use the latest supported version.-->
  <script src="https://cdn1.adoberesources.net/alloy/2.6.4/alloy.min.js" async></script>

  <!--Configure Platform Web SDK and send event-->
  <script>
    alloy("configure", {
      "edgeConfigId": "ebebf826-a01f-4458-8cec-ef61de241c93",
      "orgId":"ADB3LETTERSANDNUMBERS@AdobeOrg"
    });
    alloy("sendEvent", {
      "renderDecisions": true,
      "xdm": {
        "identityMap": {
          "GLOBAL_CUSTOMER_ID": [{
            "id": "TT8675309",
            "authenticatedState": "authenticated"
          }]
        },
        "web": {
          "webPageDetails": {
            // Other attributes included according to XDM schema
            "pageName": "product detail"
          }
        }
      },
      "data": {
        "__adobe": {
          "target": {
            "profile.gender": "male",
            "user.categoryId": "clothing",
            "entity.id": "SKU-00001-LARGE",
            "entity.categoryId": "clothing,shirts",
            "entity.customEntity": "some value",
            "cartIds": "SKU-00002,SKU-00003",
            "excludedIds": "SKU-00001-SMALL"
          }
        }
      }
    });
  </script>
</head>
<body>
  <h1 id="title">Men's Large Shirt</h1>
  <p>SKU: SKU-00001-LARGE</p>
</body>
</html>
Web SDK on an Order Confirmation page:
code language-html 
<!doctype html>
<html>
<head>
  <title>Order Confirmation</title>


  <!--Prehiding snippet for Target with asynchronous Web SDK deployment-->

  <script>
    !function(e,a,n,t){var i=e.head;if(i){
    if (a) return;
    var o=e.createElement("style");
    o.id="alloy-prehiding",o.innerText=n,i.appendChild(o),setTimeout(function(){o.parentNode&&o.parentNode.removeChild(o)},t)}}
    (document, document.location.href.indexOf("mboxEdit") !== -1, ".body { opacity: 0 !important }", 3000);
  </script>

  <!--Platform Web SDK base code-->

  <script>
    !function(n,o){o.forEach(function(o){n[o]||((n.__alloyNS=n.__alloyNS||
    []).push(o),n[o]=function(){var u=arguments;return new Promise(
    function(i,l){n[o].q.push([i,l,u])})},n[o].q=[])})}
    (window,["alloy"]);
  </script>
  <!--Platform Web SDK loaded asynchonously. Change the src to use the latest supported version.-->
  <script src="https://cdn1.adoberesources.net/alloy/2.6.4/alloy.min.js" async></script>

  <!--Configure Platform Web SDK and send event-->
  <script>
    alloy("configure", {
      "edgeConfigId": "ebebf826-a01f-4458-8cec-ef61de241c93",
      "orgId":"ADB3LETTERSANDNUMBERS@AdobeOrg"
    });
    alloy("sendEvent", {
      "xdm": {
        "identityMap": {
          "GLOBAL_CUSTOMER_ID": [{
            "id": "TT8675309",
            "authenticatedState": "authenticated"
          }]
        },
        "commerce": {
          "order": {
            "purchaseID": "ABC123",
            "priceTotal": 1337.89
          },
          "purchases": {
            "value": 1
          }
        },
        "productListItems": [{
          "SKU": "SKU-00002"
        }, {
          "SKU": "SKU-00003"
        }]
      }
    });
  </script>
</head>
<body>
  <h1 id="title">Order Confirmation</h1>
  <p>Thank you for your order</p>
</body>
</html>

Next, learn how to track Target conversion events with the Platform Web SDK.

NOTE
We are committed to helping you be successful with your Target migration from at.js to Web SDK. If you run into obstacles with your migration or feel like there is critical information missing in this guide, please let us know by posting in this Community discussion.
recommendation-more-help
a69e1b51-9545-4d8a-822d-319242c29110