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

• getVisitorValues() : Object
• getSupplementalDataID(sdidConsumerID): String
• attemptToPopulateSdidFromUrl(redirectURL)
• setCustomerIDs(object: customerIDs)
• getState() : State { OrgID: { sdid, customerIDs }
• getCookieName() : String, AMCV cookie name
• Visitor#AuthState : Static Enum

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.

getVisitorValues()

This method should be called to retrieve marketing cloud visitor ID, Audience Manager location hint and Audience Manger blob.

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

    // 2. Instantiate Visitor instance
    const visitor = new Visitor("<orgId>", amcvCookie); 

    //3. Retrieve Visitor instance values
    const visitorValues = visitor.getVisitorValues();

    ...

getSupplementalDataID(sdidConsumerID)

This method should be called to generate a supplemental data ID.

Parameter is an object with the following props:

• sdidConsumerID: As mentioned above, an sdidConsumerID must be provided.

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

    // 2. Instantiate Visitor instance
    const visitor = new Visitor("<orgId>", amcvCookie);

    //3. Retrieve SDID
    const sdid = visitor.getSupplementalDataID("<some mbox>");

    ...

attemptToPopulateSdidFromUrl(redirectURL)

This method looks for an adobe_mc_sdid param in the URL. If found, parse it and look for SDID and CONSUMER, and try to set those IDs as supplemental Data IDs.

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

    // 2. Instantiate Visitor instance
    const visitor = new Visitor("<orgId>", amcvCookie);

    //3. Attempt to populate SDIDs from
    visitor.attemptToPopulateSdidFromUrl(redirectURL);

    ...

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 }