User Identity

Managing user identities in order to improve the ability to identity returning users.

Introduction

Verada identifies users by assigning a unique anonymous identifier in their browser. Returning users are detected when they come back to your website in the same browser.

Users might use different browsers, move from a mobile device to a laptop, or periodically clear browsing data. Verada offers the ability to link users' movements across different platforms, giving a holistic view of the user journey. This is achieved by providing one or more known identities to Verada.

When you provide a known identity to Verada's integration, Verada is able to link and merge users together that share the same identity. This greatly expands your ability to glean actionable insight from the behavioural data that Verada captures.

User Identification

User identities are shared with Verada by providing an identity map object via the Page Tracking and Order Tracking integrations.

Example

The following is an example of an identity map data structure which provides details for two identities named $user and crm1.

• Each identity object has a mandatory userId property which specifies a unique user identifier for the identity type.
• The special $user identity is used to specify the ID of a logged in user on the website or app.
• The names used identity types are arbitrary and can be any alpha-numeric name which is meaningful to your environment. In this example, crm1 is used to associate the user's ID in a customer relationship management system with the Verada user identity. It also associates additional attributes via the data object.

{
  "$user": {
    "userId": "23872392383"
  },
  "crm1": {
    "userId": "b70115f2-aea8-456a-ab07-f9152257df4d",
    "data": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

Data types

IdentityMap

// An object with keys that match each
interface IdentityMap {
  [providerId: string]: Identity;
  // An optional special identity supported by Verada to represent a
  // logged-in user ID for the website.
  $user?: Identity;
}

Identity

interface Identity {
  // The unique user identifier.
  userId: string;
  // An optional object of abritrary data.
  data: {
    [key: string]: any;
  };
}

Identifying users via Page Tracking tag

The page tracking JavaScript tag supports an identities property which accepts an identity map:

{
  "version": 3,
  "accountKey": "...",
  "data": {
    "pageType": "..."
  },
  "identities": {
    "$user": {
      "userId": "23872392383"
    },
    "crm1": {
      "userId": "b70115f2-aea8-456a-ab07-f9152257df4d",
      "data": {
        "key1": "value1",
        "key2": "value2"
      }
    }
  }
}

Identifying users via the Verada Data Layer

The Verada Data Layer can be used to push identities to Verada without needing to predefine them in your Page Tracking tag.

After defining the data layer on your website, simply push identities to it as follows:

<!--
  This example assumes that you have defined the Verada Data Layer array
  somewhere earlier in the document like so:
-->
<script>
  var fanplayr_api = [];
</script>

<script>
  fanplayr_api.push({
    _type: 'identities',
    $user: {
      userId: '23872392383'
    },
    crm1: {
      userId: 'b70115f2-aea8-456a-ab07-f9152257df4d',
      data: {
        key1: 'value1',
        key2: 'value2'
      }
    }
  });
</script>

Managing Identity Providers

The Identity Management area of the Verada Portal allows you to define and manage identity providers. This information is used by Verada's Streams service to understand which user identity should be streamed with data to external endpoints you may have defined.

For example, if you have connected Verada to a CRM and wish to share include the user's CRM ID with the data that Verada streams into your CRM, you would create an identity provider for the CRM, then provide the relevant identity via one of the methods above. When Verada streams data into the CRM it will include the identity associated with it.

Each identity provided has the following properties:

• key - A unique identifier which can be any string value. This key is used in the identity map JavaScript object. E.g. "crm1".
• name - A unique display name for the identity. This is only visible in the Verada portal. E.g. "Salesforce".

Logged-in User Identity

Verada supports a special $user identity provider key which can be used to pass a logged-in user's identity for the website.

For example after a user logs into the website you can use Verada's data layer variable to associate the logged-in user's identity with the Verada user:

fanplayr_api.push({
  _type: 'identities',
  $user: {
    userId: '234902834211'
  }
});

INFO

Note: This method of specifying the user's logged-in identity is equivalent to specifying the customerId property in the Page Tracking tag. This method is the preferred method, however the customerId property will continue to work for backwards compatibility.

Merging User Identities

It is important to understand that Verada will automatically merge individual users it sees who have any identity that overlaps.

For example:

• An anonymous user visits your website for the first time. Verada associates a unique user key with their browser, e.g. "User_1234".
• Verada will continue to identify the user so long as they return with the same user key.
• Later, the user logs into the website and the website uses Verada's identity management system to inform Verada of the user's logged-in identity for the website

fanplayr_api.push({
  _type: 'identities',
  $user: {
    userId: '234902834211'
  }
});

• From this point forward, Verada will link its user key "User_1234" with the website's logged-in user identity of "234902834211".
• Later if the user returns to the website on a different device or after clearing their browsing data, Verada will assign a new user key to the user, e.g. "User_5678".
• Finally, if the user logs into the website again and Verada is provided the same logged-in user identity of "234902834211", Verada will understand that user "User_1234" and "User_5678" are the same and merge them together to form a single profile and history.