Personalization via Adobe Target

Overview

The Edge Network Server API can deliver and render personalized experiences created in Adobe Target, with the help of the Form-Based Experience Composer.

IMPORTANT

Personalization experiences created through the Target Visual Experience Composer (VEC) are not supported by the Server API.

Configure your datastream

Before you can use the Server API in conjunction with Adobe Target, you must enable Adobe Target personalization on your datastream configuration.

See the guide on adding services to a datastream, for detailed information on how to enable Adobe Target.

When configuring your datastream, you can (optionally) provide values for Property Token, Target Environment ID, and Target Third Party ID Namespace.

UI image showing the datastream service configuration screen, with Adobe Target selected

You can choose between the following Analytics Logging options:

  • Server Side: This is the default option for A4T. When this option is selected, each time personalization content is returned by Target, the relevant A4T data is automatically sent to Analytics, based on the response from the Target personalization engine.

  • Client Side: When this option is selected, each time personalization content is returned by Target, the relevant A4T data is returned to the calling application. If your intention is to record this data in Analytics, you need to ensure it is reported on a subsequent call to Analytics.

    IMPORTANT

    In addition to selecting Client Side in the Target Configuration, you must also disable Analytics, for the Edge Network to return the A4T information back to the response.

Custom parameters

Most fields in the XDM portion of each request are serialized into dot notation and then sent to Target as custom or mbox parameters.

Example

Given the following XDM sample:

"xdm":{
   "marketing":{
      "campaignGroup":"winter22",
      "campaignName":"homeOwnerPromo22",
      "trackingCode":"hop22"
   }
}

When creating audiences in Target, the following values will be available as custom parameters:

  • xdm.marketing.campaignGroup
  • xdm.marketing.campaignName
  • xdm.marketing.trackingCode

Target profile updates

The Server API allows for updates to the Target profile. To update a Target profile, ensure that the profile data is passed in the data portion of the request in the following format:

"data":  {
    "__adobe.target": {
        "profile.eyeColor": "brown",
        "profile.hairColor": "brown"
    }
}

Querying Target activities

Schemas

The query portion of the request determines what content is returned by Target. Under the personalization object, schemas determines the type of content to be returned by Target.

In situations where you are unsure of what sort of offers you’ll be retrieving, you should include all four of the schemas in your personalization query to the Edge Network:

  • HTML-based offers:
    https://ns.adobe.com/personalization/html-content-item
  • JSON-based offers:
    https://ns.adobe.com/personalization/json-content-item
  • Target Redirect offers
    https://ns.adobe.com/personalization/redirect-item
  • Target DOM Manipulation offers
    https://ns.adobe.com/personalization/dom-action

Decision scopes

Adobe Target mbox names should be included in the decisionScopes array to return the appropriate content.

Example

In the example below, all four offer types are requested along with a Target activity called serverapimbox.

"query":{
   "personalization":{
      "schemas":[
         "https://ns.adobe.com/personalization/html-content-item",
         "https://ns.adobe.com/personalization/json-content-item",
         "https://ns.adobe.com/personalization/redirect-item",
         "https://ns.adobe.com/personalization/dom-action"
      ],
      "decisionScopes":[
         "serverapimbox"
      ]
   }
}

API call example

API format

POST /ee/v2/interact

Request

A full request that includes a complete XDM object, profile paramters, along with the appropriate Target query is outlined below.

curl -X POST 'https://server.adobedc.net/ee/v2/interact?dataStreamId={DATASTREAM_ID}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org: {ORG_ID}' \
--header 'Authorization: Bearer {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "event": {
        "xdm": {
            "eventType": "web.webpagedetails.pageViews",
            "identityMap": {
                "ECID": [
                    {
                        "id": "05907638112924484241029082405297151763",
                        "authenticatedState": "ambiguous",
                        "primary": true
                    }
                ]
            },
            "web": {
                "webPageDetails": {
                    "URL": "https://alloystore.dev",
                    "name": "Home Page"
                },
                "webReferrer": {
                    "URL": ""
                }
            },
            "device": {
                "screenHeight": 1440,
                "screenWidth": 3440,
                "screenOrientation": "landscape"
            },
            "environment": {
                "type": "browser",
                "browserDetails": {
                    "viewportWidth": 3440,
                    "viewportHeight": 1440
                }
            },
            "placeContext": {
                "localTime": "2022-03-22T22:45:21.193-06:00",
                "localTimezoneOffset": 360
            },
            "timestamp": "2022-03-23T04:45:21.193Z",
            "implementationDetails": {
                "name": "https://ns.adobe.com/experience/alloy/reactor",
                "version": "1.0",
                "environment": "serverapi"
            },
            "data": {
                "__adobe": {
                    "target": {
                        "profile.eyeColor": "brown",
                        "profile.hairColor": "brown",
                        "profile.shoeColor": "black"
                    }
                }
            }
        }
    },
    "query": {
        "personalization": {
            "schemas": [
                "https://ns.adobe.com/personalization/html-content-item",
                "https://ns.adobe.com/personalization/json-content-item",
                "https://ns.adobe.com/personalization/redirect-item",
                "https://ns.adobe.com/personalization/dom-action"
            ],
            "decisionScopes": [
                "serverapimbox"
            ]
        }
    }
}'

Response

The Edge Network will return a response similar to the one below.

{
   "requestId":"10959bbf-f83d-40e1-9521-d9145f19cdc5",
   "handle":[
      {
         "payload":[
            {
               "id":"AT:eyJhY3Rpdml0eUlkIjoiMTQwMjgxIiwiZXhwZXJpZW5jZUlkIjoiMCJ9",
               "scope":"serverapimbox",
               "scopeDetails":{
                  "decisionProvider":"TGT",
                  "activity":{
                     "id":"140281"
                  },
                  "experience":{
                     "id":"0"
                  },
                  "strategies":[
                     {
                        "algorithmID":"0",
                        "trafficType":"0"
                     }
                  ],
                  "characteristics":{
                     "eventToken":"xycjBJlZhwVV5MN0kMkmoGqipfsIHvVzTQxHolz2IpTMromRrB5ztP5VMxjHbs7c6qPG9UF4rvQTJZniWgqbOw=="
                  }
               },
               "items":[
                  {
                     "id":"282484",
                     "schema":"https://ns.adobe.com/personalization/json-content-item",
                     "meta":{
                        "offer.name":"/server_apiform/experiences/0/pages/0/zones/0/1648103551041",
                        "experience.id":"0",
                        "activity.name":"Server API Form",
                        "activity.id":"140281",
                        "experience.name":"Experience A",
                        "option.id":"2",
                        "offer.id":"282484"
                     },
                     "data":{
                        "id":"282484",
                        "format":"application/json",
                        "content":{
                           "value":"a/b json experience a",
                           "platform":"server"
                        }
                     }
                  }
               ]
            }
         ],
         "type":"personalization:decisions",
         "eventIndex":0
      },
      {
         "payload":[
            {
               "key":"kndctr_53A16ACB5CC1D3760A495C99_AdobeOrg_identity",
               "value":"CiYwNTkwNzYzODExMjkyNDQ4NDI0MTAyOTA4MjQwNTI5NzE1MTc2M1IOCL-pwpv9LxgBKgNPUjLwAb-pwpv9Lw==",
               "maxAge":34128000
            }
         ],
         "type":"state:store"
      }
   ]
}

If the visitor qualifies for a personalization activity based on the data sent to Adobe Target, the relevant activity content will be found under the handle object, where the type is personalization:decisions.

Other content will sometimes be returned under handle as well. Other content types are not relevant to the Target personalization. If the visitor qualifies for multiple activities, each activity will be a separate personalization object in the array.

The table below explains the key elements of that portion of the response.

Property Description Example
scope The Target mbox name that resulted in the proposed offers. "scope": "serverapimbox"
items[].schema The schema of the content associated with the proposed offer. This will be related to the activity type you selected when creating the personalization activity. "schema": "https://ns.adobe.com/personalization/json-content-item",
items[].meta.activity.id The unique ID of the offer activity. Typically a 6-digit number. "activity.id": "140281"
items[].meta.activity.name The name of the user-specified offer activity. This is provided during the activity creation step. "activity.name": "Server API Form"
items[].meta.experience.id The unique ID of the personalization experience. "experience.id": "0"
items[].meta.experience.name The unique name of the personalization experience. "experience.name": "Experience A"
items[].data.id The ID of the proposed offer. "id": "282484"
items[].data.format The format of the content associated with the proposed offer. "format: "application/json
items[].data.content Content associated with the proposed offer. This will be used for personalization of content of the calling application. "content": "<CONTENT CONFIGURED IN TARGET>"

On this page