Using the ID Service with A4T and a server-side implementation of Target

These instructions are for A4T customers with mixed server- and client-side implementations of Target, Analytics, and the ID service. Customers who need to run the ID service in a NodeJS or Rhino environment should also review this information. This instance of the ID service uses a shortened version the VisitorAPI.js code library, which you download and install from Node Package Manager (NPM). Review this section for installation instructions and other configuration requirements.

Introduction

A4T (and other customers) can use this version of the ID service when they need to:

Code download and provided interfaces

See the ID service NPM repository to download the server-side code package and review the interfaces included in the current build.

Workflow

The diagram and sections below describe what happens, and what you need to configure, in each step of the server-side implementation process.

Step 1: Request page

Server-side activity begins when a visitor makes an HTTP request to load a web page. During this step, your server receives this request and checks for the AMCV cookie. The AMCV cookie contains the visitor’s Experience Cloud ID (MID).

Step 2: Generate ID Service payload

Next, you need make a server-side payload request to the ID service. A payload request:

Your payload request should look like following code sample. In the code sample, the visitor.setCustomerIDs function is optional. See Customer IDs and Authentication States for more information.

//Import the ID service server package
var Visitor = require("@adobe-mcid/visitor-js-server");

//Pass in your Organization ID to instantiate Visitor
var visitor = new Visitor("Insert Experience Cloud ID here");

//
<i>(Optional)</i> Set a custom customer ID
visitor.setCustomerIDs({
     userid:{
          id:"1234",
          authState: Visitor.AuthState.UNKNOWN //AuthState is a static property of the Visitor class
     }
});

//Parse the visitor's HTTP request for the AMCV cookie
var cookies = cookie.parse(req.headers.cookie || "");
var cookieName = visitor.getCookieName(); // Visitor API that returns the cookie name.
var amcvCookie = cookies[cookieName];

//Generate the payload request pass your mbox name and the AMCV cookie if present
var visitorPayload = visitor.generatePayload({
     mboxName: "bottom-banner-mbox",
     amcvCookie: amcvCookie
});

The ID service returns the payload in a JSON object similar to the following example. Payload data is required by Target.

{
    "marketingCloudVisitorId": "02111696918527575543455026275721941645",
    "mboxParameters": {
        "mboxAAMB": "abcd1234",
        "mboxMCGLH": "9",
        "mboxMCSDID": "56BE026543F7E211-1CC51BCAAE88F0D2",
        "vst.userid.id": "1234567890",
        "vst.userid.authState": 0
    }
}

If your visitor doesn’t have an AMCV cookie, the payload omits these key-value pairs:

Step 3: Add payload to the Target call

After your server receives payload data from the ID service, you need to instantiate additional code to merge it with data passed in to Target. The final JSON object passed to Target would look similar to this:

{
"mbox" : "target-global-mbox",
"marketingCloudVisitorId":"02111696918527575543455026275721941645",
"requestLocation" : {
     "pageURL" : "http://www.domain.com/test/demo.html",
     "host" : "localhost:3000"
     },
"mboxParameters" : {
     "mboxAAMB" : "abcd1234",
     "mboxMCGLH" : "9",
     "mboxMCSDID": "56BE026543F7E211-1CC51BCAAE88F0D2",
     "vst.userid.id": "1234567890",
     "vst.userid.authState": 0,
     }
}

Step 4: Get server state for the ID Service

Server state data contains information about work that’s been done on the server. The client-side ID service code requires this information. Customers who have implemented the ID service through Dynamic Tag Manager (DTM) can configure DTM to pass server state data through that tool. If you’ve set up the ID service through a non-standard process, you will need to return server state with your own code. The client-side ID service and Analytics code passes state data to Adobe when the page loads.

Get server state via DTM

If you have implemented the ID service with DTM, you need to add code to your page and specify a name-value pair in the DTM settings.

Page Code

Add this code to the <head> tag of your HTML page:

//Get server state
var serverState = visitor.getState();

Response.send("
...
<head>
     <script>
          //Add 'serverState' as a stringified JSON global variable.
          "var serverState = "+ JSON.stringify(serverState) +";
     </script>
     <script src = "DTM script (satellite JS)">
     </script>
</head>
...

DTM Settings

Add these as name-value pairs to the General > Settings section of your ID service instance:

Your configured settings should look like this:

Get server state without DTM

If you have a non-standard implementation of the ID service, you must configure this code to run on your server while it assembles the requested page:

//Get server state
var serverState = visitor.getState();

Response.send("
...
<head>
     <script src="VisitorAPI.js"></script>
     <script>
          var visitor = Visitor.getInstance(orgID, {
          serverState: serverState
          ...
     </script>
</head>
...

Step 5: Serve a page and return Experience Cloud data

At this point, the web server sends page content to the visitor’s browser. From this point on, the browser (not the server) makes all the remaining ID service and Analytics calls. For example, in the browser: