Working with identities

Track user identities with session IDs, e-commerce IDs, segments, and traits using SDK, GTM, or REST API, ensuring accurate tracking, personalization, and GDPR compliance.

To send an event, you have to provide at least one identifier: the session ID. When a visitor arrives at your website or app, they may initially be anonymous until they log in. During their visit, you can generate an anonymous session ID to track their journey. Store the session ID locally (in a cookie or local storage) and include it with every event using the user.identities.sessionId field.

In the sections below, we go into detail about how to implement identities with each implementation method.

SDK

Session ID

If you are using the Javascript SDK, a random session ID is created for the visitor and automatically stored in local storage as attraqtsessionid. This session ID is then attached to any event sent through the library.

If you have a different session ID that's generated elsewhere in your system and want to use it, add it through the addUserIdentity method:

xo.activity.addUserIdentity('sessionId', 'session-id');

The SDK only stores the session ID in local storage. You will need to re-add any additional identities each time a page is loaded.

Logins

Once the shopper logs in, you know exactly who they are through the ID you have for them in your system, for example an e-commerce ID. The e-commerce ID can then be added to subsequent events along with the already existing session ID.

Adding an identity

Use addUserIdentity to add a different identity, e.g. the e-commerce ID:

xo.activity.addUserIdentity('ecommerceId', 'e-commerce-id');

Adding multiple identities

Use the setUserIdentities method to add multiple identities at once or to overwrite any pre-existing identities added with addUserIdentity:

const identities = { 
    ecommerceId: 'e-commerce-id', 
    sessionId: 'session-id' 
};

xo.activity.setUserIdentities(identities);

Example: Handling user identities

The following sequence demonstrates how the SDK handles user identities and ensure accurate tracking throughout a user's journey on your platform:

1. User arrives on your platform: The SDK assigns a default session ID and stores it in local storage.

2. User performs actions: The SDK attaches the session ID to any activity event you send out through the SDK.

3. User logs in: You retrieve the user's e-commerce ID from the login and attach it to all subsequent events.

4. User performs more actions: The SDK attaches both the newly added e-commerce ID as well as the already existing session ID to any activity event you send out. On the first activity sent this way, we attribute the session ID to the e-commerce ID, so all previous actions are now assigned to the same user.

Segments and Traits (XO specific)

This section is relevant for XO customers only.

Apart from identities, the SDK can also handle segments and traits. Segments constitute labels to qualify groups of users sharing common traits or behaviors, such as "Frequent buyer" or "Prospect". Traits constitute various qualifying values related to the user in question, including profile, and preference data, age, gender, likes, etc.

Setting a user segment

Use the addUserSegment method to set a user segment. For example:

xo.activity.addUserSegment('new');

Setting multiple user segments

Use the setUserSegments method to set multiple segments at once and overwrite any pre-existing ones set by addUserSegment. For example:

const segments = ['new', 'prospect'];

xo.activity.setUserSegments(segments);

Adding a trait

Use the addUserTrait method to add a trait for the user. For example:

xo.activity.addUserTrait('age', '45');

Adding multiple traits

Use the setUserTraits method to set multiple traits for the user at once and overwrite any pre-existing ones set by addUserTrait. For example:

var traits = {
    age: 45,
    buyer: true
};

xo.activity.setUserTraits(traits);

Traits are information you know about your users and that you want to use in our platform. You must only send information relevant to the platform usage and avoid sending personal information.

Logouts

If a user logs out, you shouldn't continue to attribute any future events to the same user until they log in again. To clear all user information (and generate a new session id) use the clearUser method:

xo.activity.clearUser();

Opting Out

In order to be compliant with GDPR policies, you must allow your users to opt-out of saving cookies and having their information tracked. You should not be tracking any information on such users, and should refrain from sending any events.

When using the SDK to send activity events and the user decides to opt-out, call the following method:

xo.activity.optOut();

If the user decides to opt-in again, use the following method:

xo.activity.optIn();

Handling the user object yourself

If you would like to set the complete user object, you can override any pre-existing configuration through the setUser method:

const user = {
    'identities': {
        'sessionId': 'session-id',
    },
    'segments': ['new']
}

attraqt.activity.setUser(user);

You can also attach the user object as part of the activity object every time you send an activity, for example:

const activity = {
  "action": "view",
  "target": {
    "product": "123"
  },
  "user": {
    "identities": {
      "sessionId": "f49c75a2-6994-41e2-875d-97ec4d19254b",
      "ecommerceId":"0ca79556-2fee-11eb-adc1-0242ac120002"
    },
    "segments": ["new", "prospect"],
    "traits": {
      "age": 45,
      "buyer": true
    }
  }
};

xo.activity.send(activity);

GTM

If you are using our GTM templates, identities are added as key-value pairs in the Identities section.

To add segments or traits, include them in the User information section.

REST API

If you are using the REST API to send events, you can attach the user object as part of the activity object every time you send an activity. For example:

curl "https://collect-eu.attraqt.io/30cbb5fc-375f-4cf2-8efd-ed86d909718e"
      -X POST 
      -H "Content-Type: application/json"
      -d '{
            "action": "view",
            "target": {
              "product": "123"
            },
            "user": {
              "identities": {
                "sessionId": "session-id",
                "ecommerceId":"e-commerce-id"
              },
              "segments": ["new", "prospect"],
              "traits": {
                "age": 45,
                "buyer": true
              }
            }
          }'