@adobe-mcid/visitor-js-server

Visitor JS - Server Side

This is a trimmed down version of the VisitorAPI JS library. It is designed to run on your 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

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

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.

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

What is an sdidConsumerID

sdidConsumerID is a unique string used to intentify the consumer.

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. 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. Merge the `visitorPayload` with you target specific into and make the Target call.
    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.

IMPORTANT:

• 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"
});

See Customer IDs and Authentication States

Visitor#AuthState

AuthState enum to be used when setting Customer IDs.

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