User Identity

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

Introduction

Fanplayr 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. Fanplayr 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 Fanplayr.

When you provide a known identity to Fanplayr's integration, Fanplayr 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 Fanplayr captures.

User Identification

User identities are shared with Fanplayr 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 Fanplayr 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 Fanplayr 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 Fanplayr Data Layer

The Fanplayr Data Layer can be used to push identities to Fanplayr 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 Fanplayr 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 Fanplayr Portal allows you to define and manage identity providers. This information is used by Fanplayr'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 Fanplayr to a CRM and wish to share include the user's CRM ID with the data that Fanplayr 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 Fanplayr 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 Fanplayr portal. E.g. "Salesforce".

Logged-in User Identity

Fanplayr 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 Fanplayr's data layer variable to associate the logged-in user's identity with the Fanplayr user:

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

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 Fanplayr 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. Fanplayr associates a unique user key with their browser, e.g. "User_1234".

• Fanplayr 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 Fanplayr's identity management system to inform Fanplayr of the user's logged-in identity for the website

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

• From this point forward, Fanplayr 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, Fanplayr will assign a new user key to the user, e.g. "User_5678".

• Finally, if the user logs into the website again and Fanplayr is provided the same logged-in user identity of "234902834211", Fanplayr will understand that user "User_1234" and "User_5678" are the same and merge them together to form a single profile and history.