DocumentationExperience PlatformWeb SDK Guide

Using Offer Decisioning with the Platform Web SDK

Last update: Wed Dec 06 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
  • User
  • Admin
  • Leader
NOTE
The use of Offer Decisioning in Adobe Experience Platform Web SDK is available in early access to select users. This functionality is not available to all organizations.

Adobe Experience Platform Web SDK can deliver and render personalized offers that are managed in Offer Decisioning. You can create your offers and other related objects using the Offer Decisioning user interface (UI) or APIs.

Prerequisites

  • Organization is enabled for edge decisioning
  • Offers, Activities created
  • Datastream is published

Terminology

It is important to understand the following terminology when working with Offer Decisioning. For more information and to view additional terms, please visit the Offer Decisioning glossary.

  • Container: A container is an isolation mechanism to keep different concerns apart. The container ID is the first path element for all repository APIs. All decisioning objects reside within a container.

  • Decision Scopes: For Offer Decisioning, decision scopes are the Base64 encoded strings of JSON containing the activity and placement IDs you want the offer decisioning service to use to propose offers.

    Decision scope JSON:

    code language-json 
    {
  "activityId":"xcore:offer-activity:11cfb1fa93381aca",
  "placementId":"xcore:offer-placement:1175009612b0100c"
}

    Decision scope Base64 encoded string:

    code language-json 
    "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ=="
    note tip
    TIP
    You can copy the decision scope value from the Activity Overview page in the UI.

    Decision copy settings.

  • Datastreams: For more information, please read the datastreams documentation.

  • Identity: For more information, please read this documentation outlining how Platform Web SDK uses Identity Service.

Enabling Offer Decisioning

To enable Offer Decisioning, perform the following steps:

  1. Enabled Adobe Experience Platform in your datastream and check the “Offer Decisioning” box

    offer-decisioning-edge-config

  2. Follow the instructions to install the SDK (The SDK can be installed standalone or through the UI. See the tags quick start guide) for more information.

  3. Configure the SDK for Offer Decisioning. Additional Offer Decisioning specific steps are provided below.

    • Install the standalone SDK

      1. Configure the “sendEvent” action with your decisionScopes

        code language-javascript 
         alloy("sendEvent", {
    ...
    "decisionScopes": [
        "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTIxYWIwOWMxM2JkZDIyNCIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjEyMWFiMDZhODRkMDViMTEifQ==",
        "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTIxYWIyNWI5NTUwNWIxZiIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjEyMWFiMjFmOTQzMDE0MmIifQ=="
    ]
 })

    • Install the SDK through tags

      1. Create a tag property

      2. Add the embed code

      3. Install and configure the Platform Web SDK extension with the Datastream you created by selecting the configuration from the “Datastream” dropdown. See the documentation on extensions.

        install-aep-web-sdk-extension

        configure-aep-web-sdk-extension

      4. Create the necessary Data Elements. At the bare minimum, you must create a Platform Web SDK Identity Map and a Platform Web SDK XDM Object data element.

        identity-map-data-element

        xdm-object-data-element

      5. Create your Rules.

        • Add a Platform Web SDK Send Event action and add the relevant decisionScopes to that action’s configuration

          send-event-action-decisionScopes

      6. Create and publish a library containing all the relevant Rules, Data Elements, and Extensions you have configured

Sample requests and responses

One decisionScopes value

Request

{
  "events": [
    {
      "xdm": {
        "identityMap": {
          "ECID": [
            {
              "id": "91133425615229052182584359620783097099"
            }
          ]
        }
      },
      "query": {
        "personalization": {
          "decisionScopes": [
            "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ=="
          ]
        }
      }
    }
  ]
}
Property
Required
Description
Limits
Example
identityMap
Yes
Refer to this Identity Service documentation.
One identity per request.
{ "identityMap": { "ECID": [ { "id": "91133425615229052182584359620783097099" } ] } }.

Note: Users don’t need to include the ECID parameter in the API call. This parameter is automatically added to the call if needed.
decisionScopes
Yes
An array of Base64 encoded strings of JSON containing the activity and placement IDs.
Maximum 30 decisionScopes per request.
"decisionScopes": ["eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ=="]

Response

{
  "requestId": "94c4f2f1-9218-43ce-afd3-eb0d853c5174",
  "handle": [
    {
      "payload": [
        {
          "id": "2862bb89-5df2-4bc6-85c2-d8f7e1a091de",
          "scope": "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ==",
          "activity": {
            "id": "xcore:offer-activity:11cfb1fa93381aca",
            "etag": "2"
          },
          "placement": {
            "id": "xcore:offer-placement:1175009612b0100c",
            "etag": "1"
          },
          "items": [
            {
              "id": "xcore:personalized-offer:124cc332095cfa74",
              "schema": "https://ns.adobe.com/experience/offer-management/content-component-html",
              "etag": "1",
              "data": {
                "id": "xcore:personalized-offer:124cc332095cfa74",
                "format": "text/html",
                "language": [
                  "en-US"
                ],
                "content": "<p>20% Off on shipping</p>",
                "characteristics": {
                  "foo": "bar",
                  "foo1": "bar1"
                }
              }
            }
          ]
        }
      ],
      "type": "personalization:decisions",
      "eventIndex": 0
    }
  ]
}
Property
Description
Example
scope
The decision scope that resulted in the proposed offers.
"scope": "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ=="
activity.id
The unique ID of the offer activity.
"id": "xcore:offer-activity:11cfb1fa93381aca"
placement.id
The unique ID of the offer placement.
"id": "xcore:offer-placement:1175009612b0100c"
items.id
The ID of the proposed offer.
"id": "xcore:personalized-offer:124cc332095cfa74"
schema
The schema of the content associated with the proposed offer.
"schema": "https://ns.adobe.com/experience/offer-management/content-component-html"
data.id
The ID of the proposed offer.
"id": "xcore:personalized-offer:124cc332095cfa74"
format
The format of the content associated with the proposed offer.
"format": "text/html"
language
An array of languages associated with the content from the proposed offer.
"language": [ "en-US" ]
content
Content associated with the proposed offer in the format of a string.
"content": "<p style="color:red;">20% Off on shipping</p>"
deliveryUrl
Image content associated with the proposed offer in the format of a URL.
"deliveryURL": "https://image.jpeg"
characteristics
Characteristics associated with the proposed offer in the format of a JSON object.
"characteristics": { "foo": "bar", "foo1": "bar1" }

Multiple decisionScopes values

Request

{
  "events": [
    {
      "xdm": {
        "identityMap": {
          "ECID": [
            {
              "id": "91133425615229052182584359620783097099"
            }
          ]
        }
      },
      "query": {
        "personalization": {
          "decisionScopes": [
            "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ==",
            "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTIyMjA4YjNhODc0MDU1OCIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjEyMjIwNDUyOTUxNGEyYzAifQ==",
            "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTIyYzkxMzg1Mjc2MDE4YyIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjEyMzMxZjU2MTYyYWEyZjcifQ=="
          ]
        }
      }
    }
  ]
}
Property
Required
Description
Limits
Example
identityMap
Yes
Refer to this Identity Service documentation.
One identity per request.
{ "identityMap": { "ECID": [ { "id": "91133425615229052182584359620783097099" } ] } }.

Note: Users don’t need to include the ECID parameter in the API call. This parameter is automatically added to the call if needed.
decisionScopes
Yes
An array of Base64 encoded strings of JSON containing the activity and placement IDs.
Maximum 30 decisionScopes per request.
"decisionScopes":["eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ==", "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTIyMjA4YjNhODc0MDU1OCIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjEyMjIwNDUyOTUxNGEyYzAifQ=="

Response

{
  "requestId": "94c4f2f1-9218-43ce-afd3-eb0d853c5174",
  "handle": [
    {
      "payload": [
        {
          "id": "a2804dfb-a0ec-4df9-8311-59d3ecdeb642",
          "scope": "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MTEyMyIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDExMjMifQ==",
          "activity": {
            "id": "xcore:offer-activity:11cfb1fa93381123",
            "etag": "1"
          },
          "placement": {
            "id": "xcore:offer-placement:1175009612b01123",
            "etag": "3"
          },
          "items": [
            {
              "id": "xcore:personalized-offer:11e36d4a22954123",
              "schema": "https://ns.adobe.com/experience/offer-management/content-component-text",
              "etag": "2",
              "data": {
                "id": "xcore:personalized-offer:11e36d4a22954123",
                "format": "text/text",
                "language": [
                  "en"
                ],
                "content": "20% Off on shipping",
                "characteristics": {
                  "foo2": "bar2"
                }
              }
            }
          ]
        },
        {
          "id": "a2804dfb-a0ec-4df9-8311-59d3ecdeb642",
          "scope": "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ==",
          "activity": {
            "id": "xcore:offer-activity:11cfb1fa93381aca",
            "etag": "2"
          },
          "placement": {
            "id": "xcore:offer-placement:1175009612b0100c",
            "etag": "1"
          },
          "items": [
            {
              "id": "xcore:personalized-offer:11e36d4a2295415d",
              "schema": "https://ns.adobe.com/experience/offer-management/content-component-imagelink",
              "etag": "1",
              "data": {
                "id": "xcore:personalized-offer:11e36d4a2295415d",
                "format": "image/png",
                "language": [
                  "en"
                ],
                "deliveryURL": "https://image.jpeg",
                "characteristics": {
                  "foo": "bar",
                  "foo1": "bar1"
                }
              }
            }
          ]
        }
      ],
      "type": "personalization:decisions",
      "eventIndex": 0
    }
  ]
}
Property
Description
Example
scope
The decision scope that resulted in the proposed offers.
"scope": "eyJhY3Rpdml0eUlkIjoieGNvcmU6b2ZmZXItYWN0aXZpdHk6MTFjZmIxZmE5MzM4MWFjYSIsInBsYWNlbWVudElkIjoieGNvcmU6b2ZmZXItcGxhY2VtZW50OjExNzUwMDk2MTJiMDEwMGMifQ=="
activity.id
The unique ID of the offer activity.
"id": "xcore:offer-activity:11cfb1fa93381123"
placement.id
The unique ID of the offer placement.
"xcore:offer-placement:1175009612b01123"
items.id
The ID of the proposed offer.
"id": "xcore:personalized-offer:11e36d4a22954123"
schema
The schema of the content associated with the proposed offer.
"schema": "https://ns.adobe.com/experience/offer-management/content-component-text"
data.id
The ID of the proposed offer.
"id": "xcore:personalized-offer:11e36d4a22954123"
format
The format of the content associated with the proposed offer.
"format": "text/text"
language
An array of languages associated with the content from the proposed offer.
"language": [ "en-US" ]
content
Content associated with the proposed offer in the format of a string.
"content": "<p style="color:red;">20% Off on shipping</p>"
deliveryUrl
Image content associated with the proposed offer in the format of a URL.
"deliveryURL": "https://image.jpeg"
characteristics
Characteristics associated with the proposed offer in the format of a JSON object.
"characteristics": { "foo": "bar", "foo1": "bar1" }

Limitations

Some offer constraints are currently not supported with the mobile Edge Network workflows, for example Capping. The Capping field value specifies the number of times an offer can be presented across all users. For more details, see Offer eligibility rules and constraints documentation.

recommendation-more-help
def05a9c-d048-422c-a3a1-88b2de863f4f