Identify Method

Overview

The identify method is used to identify, create and update users in CrossEngage. This means that anytime you can relate user's actions or attributes to a recognizable user ID, you should consider triggering identify e.g. when a user logs in, updates their profile or signs up for a newsletter.

The identify method is also used as a means to update users in the CrossEngage platform in real time and can be executed with every trait.

You do not need to call identify for anonymous visitors of your website as CrossEngage automatically assigns them an anonymous xngGlobalUserId.

Personal information can be sent via web tracking but we recommend to transmit sensitive information (like address, telephone etc) per API or upload via feed.

The identify method has the following structure:

analytics.identify([externalId],[attributes]);

Method Parameters

Value	Type	Description
externalId	string	The ID of the user you are identifying. Mandatory unless noUserId is present within the attributes object.
attributes	object	Object that contains information about the user you are creating or updating, see examples below. The key noUserId is mandatory if externalId is not included when calling the function.

Implementation

id and email (and also businessUnit) needs to be available in your data layer before you fire the request to us. If not, this might cause issues with data and will lead to incorrect mapping.

This section goes through the methods that can be used for user identification in cases where an id is known and when it is not.

Identify users with an id

var externalId = '12345abcd';
var attributes = { 
    "name": "John Doe", 
    "email":"[e-mail]", 
    "plan": "tier3", 
    "logins": 10, 
    "street": "6th St", 
    "city": "Berlin", 
    "state": "Berlin", 
    "postalCode": "10557", 
    "country": "Germany" 
}; 
analytics.identify(externalId, attributes);

Using a tag manager

1. Copy the snippet.

2. Create a custom HTML tag on your tag manager and paste the snippet between <script></script> HTML tags.

3. Set up a trigger which fires upon the form's submission

Without a tag manager

Identifying a user using email

For cases when you may not have access to the externalId, CrossEngage allows you to identify users using email.

var attributes = { 
    "name": "John Doe", 
    "email": "[e-mail]", 
    "plan": "tier3", 
    "logins": 10
}; 

analytics.identify(attributes);

Please note that CrossEngage automatically fills the businessUnit property with an empty string when it is not provided. This will prevent the duplication of profiles with the same email address which do not have a business unit.

Use cases

A user enters their email to sign up for a newsletter and submits the form

The identify call should create the user based on their email without the externalId field. Consider also sending the subscription status as an optional trait.

var attributes = {
    "email": "[e-mail]",
    "noUserId": "true",
    "subscriptionStatus": "true"
}
analytics.identify(attributes);

A user logs in using their username and password

Upon successful login, call the identify function with a setup as per below:

var externalId = "211519787" 
var attributes = {
    "name": "John Doe",
    "logins": 10
}
analytics.identify(externalId, attributes);

A user signs up using their personal information

Upon successful registration, call the identify function with the newly created externalId and any newly gathered information:

var externalId = "211519787" 
var attributes = {
    "name": "John Doe",
    "plan": "tier3", 
}
analytics.identify(externalId, attributes);

You should consider sending all of the information that the user provided in their registration form so the user is set up on the CrossEngage platform in real time.

Never send any user passwords or tokens through CrossEngage web tracking functions.

A user changes their address information

Upon form submission, call the identify function with the new address values:

var externalId = "211519787" 
var attributes = {
    "address": "Bertha-Benz-Strasse 5",
    "postCode": "10557", 
    "city": "Berlin",
    "country": "Germany"
}
analytics.identify(externalId, attributes);

This ensures that this user's data is updated on the CrossEngage platform in real time. For example, after an update is made, direct mail campaigns can immediately have access to the most recent address information.