@adobe-mcid/visitor-js-server

Visitor JS - Server Side

A trimmed down version of the VisitorAPI JS library, that is meant to run on the server, either in a NodeJS or Rhino environment.

Provided Interfaces

• generatePayload(sdidConsumerID: string, amcvCookie: string) : VisitorPayload
• getState() : State { OrgID: { sdid, customerIDs }
• Visitor#AuthState : Static Enum
• getCookieName : AMCV cookie name
• setCustomerIDs (object: customerIDs)

What is an sdid

Customer who are implementing Target client-side, don't need to worry about sdid.

When implementing Target server side, and Analytics client side, you need some sort of mechanism to synchronize the states between the client and the server. SDID is part of this state, which is an ID that allows us to combine calls to Target and calls to Analytics into a cohesive set of data.

SDID is a randomly generated string that is sent in on each call that needs to be combined into a single Analytics entry.

What is an sdidConsumerID

All calls to Target that needs to combined must have the same SDID. Each of those calls need to have a unique sdidConsumerID in order for them to receive the SAME SDID.

In order to properly combine data, you must call visitor#generatePayload for every call to target, passing a unique sdidConsumerID for each call. We recommend using mbox names as sdidConsumerID.

generatePayload

This method should be called for every Target call to generate an object that gets merged into the Target request.

Parameters:

• sdidConsumerID: As mentioned above, an sdidConsumerID must be provided.
• amcvCookie: If an AMCV cookie exists in the browser request, you will need to provide it as well. Use the visitor#getCookieName helper to retrieve the cookie name related to your OrgID.

    // 1. Try to retrieve the AMCV cookie from the request.
    var cookies = cookie.parse(req.headers.cookie || "");
    var cookieName = visitor.getCookieName();
    var amcvCookie = cookies[cookieName];

    // 2. Generate Visitor Payload by passing sdidConsumerID (mbox name/id) and AMCV Cookie if found in Req:
    var visitorPayload = visitor.generatePayload({ 
        sdidConsumerID: mboxName,
        amcvCookie: amcvCookie 
    });

    // 3. At this point, you are ready to make the Target call. Mixin the `visitorPayload` with you target 
    // specific Target and make the call:
    // For example:
    var targetPayload = {
            requestLocation: {
            "pageURL" : config.pageURL,
            "impressionId" : "1",
            "host" : config.host
        },
        thirdPartyId: xxx,
        tntId: xxx
    };
    var fullPayload = Object.assign({}, visitorPayload, targetPayload);
    ...

getState

This method returns the internal state of the Visitor instance, which should be shared with the VisitorAPI client side library later on.

getCookieName

Simple helper that provides the AMCV cookie name to be retrieved from the Request.

setCustomerIDs

The setCustomerIDs method accepts multiple customer IDs for the same visitor. This helps you identify or target an individual user across different devices. For example, you can upload these IDs as customer attributes to the Marketing Cloud and access this data across the different solutions.

On the server, we are using this method to share those ids with Target, as well as adding them to the state that is shared with the client side VisitorAPI library.

NOTE:

• In order for those IDs to make it into the Target call, make sure you call setCustomerIDs before calling generatePayload.
• If you call setCustomerIDs on the server, those IDs will be added to the state that gets shared with the client, and setCustomerIDs will be automatically called on the client so you don't have to do it again. You only need to call setCustomerIDs on the client if you have more ids to set, in addition to the ones you set on the server already.
• Use the static enum Visitor.AuthState to set the authState property of the customerIds.

// Single ID with a single authentication state
visitor.setCustomerIDs({
    "userid": {
        "id": "67312378756723456",
        "authState": Visitor.AuthState.AUTHENTICATED
    }
});

/* 
Multiple IDs with only the first ID explicitly assigned an authentication state.
The second ID is not explicitly assigned an authentication state and is implicitly
assigned Visitor.AuthState.Unknown by default.
*/
visitor.setCustomerIDs({
    "userid": {
        "id": "67312378756723456",
        "authState": Visitor.AuthState.AUTHENTICATED
    },
    "puuid": "550e8400-e29b-41d4-a716-446655440000"
});

Read more

Visitor#AuthState

AuthState enum to be used when setting Customer IDs.

{ UNKNOWN: 0, AUTHENTICATED: 1, LOGGED_OUT: 2 }