Drift.identify() Implementation Guide

The Problem

Ideally, whenever someone visits your website, you would already know who they are. Are they an existing client? A sales prospect that has been to your page before? A complete stranger? Drift attempts to answer these questions with the common practice of assigning cookies to a browser when a site is first visited. If those cookies aren't removed (such as closing an incognito session) and the person returns (while on the same device and browser), Drift will recognize the visitor and continue to associate activity on your site with the same record in Drift. Some of Drift's native integrations already leverage cookies from other systems to augment and enhance your knowledge about the site visitor (Marketo and Hubspot cookies for example). But what if your site has other ways to help identify visitors? The most obvious scenario is when a visitor logs into your site. Now you know exactly who they are. But how do you share this information with Drift?

Drift has a client side method, drift.identify(), and server side endpoint, https://driftapi.com/contacts/, that allow you to pass information about a site visitor into Drift to be used for playbook targeting, service and support, personalization, and generally just a better experience for the visitor- they don't have to tell you their email address again. The method lets you assign your own unique id to the contact's record in Drift (vs using the Drift randomly created identifier). Your unique id allows you to reference, retrieve or update the correct record in Drift when the person logs-in again or as needed via our API endpoints.

To best understand how to use drift.identify(), it's helpful to start with an explanation of how Drift works without it.

Organic Drift (ie. not implementing drift.identify())

When a site visitor points their browser at a page where your Drift snippet is installed a few processes occur before Drift appears on the page.

The Drift Widget is bootstrapped (aka loaded as a global object on the page).
Drift checks for the presence of a cookie, specifically the drift_aid (aid = anonymous id).
If no drift_aid is present, a new drift_aid is generated and stored in the browser. Drift creates unguessable and unique values that look something like this: 189f059b-4b5e-4c28-988c-b1764ae86efc
While this cookie is present in the visitor's browser, any activity they have with Drift will be associated with a contact record that has an externalId equal to the drift_aid value. How do I see a contact's externalId?
Page visits and any contact attributes collected (like email, or phone number) will be associated with the Drift contact with an externalId equal to the drift_aid value.
If the visitor clears their browser or views your site from a new device, a new drift_aid and subsequent contact record will be created. Any data collected under the previous drift_aid will not be associated with the visitor. This applies even if they provide the same email address under the new drift_aid. This is one way you may accumulate multiple contact records in Drift with the same email address. Why doesn't Drift prevent duplicate email addresses?

Drift with drift.identify()

The process is slightly different when using drift.identify().

When a site visitor points their browser at a page where your Drift snippet is installed a few processes occur before Drift appears on the page.

The Drift Widget is bootstrapped (aka loaded as a global object on the page).
Drift checks for the presence of a cookie, specifically the drift_aid (aid = anonymous id).
If no drift_aid is present, a new drift_aid is generated and stored in the browser. Drift creates unguessable and unique values that look something like this: 189f059b-4b5e-4c28-988c-b1764ae86efc
The site visitor logs-in and a unique identifier is passed to Drift via a client-side call to drift.identify(). Drift finds the existing record or creates a new contact record with an externalId equal to the uniqueId used in the call to drift.identify(). Either way, Drift now associates the drift_aid with a specific contact record in Drift.
After login and while this cookie is present in the visitor's browser, any activity they have with Drift will be associated with a contact record that has an externalId equal to the uniqueId value provided during the log-in process.
Page visits and any contact attributes collected (like email, or phone number) will be associated with the Drift contact with an externalId equal to the uniqueId value.
If the visitor clears their browser cookies or views your site from a new device, a new drift_aid and subsequent contact record will be created. Once the site visitor logs-in and drift.identify() is called again, their new drift_aid will be associated with their uniqueId. Any data collected after drift.identify() is called will be associated with the visitor.

Flow Diagram

Click on the image to expand

What is drift.identify()

drift.identify() is a client-side function that can be added to any page where the Drift install snippet exists. Calling drift.identify() tells Drift to associate the site visitor's subsequent activity with a specific identity. If the specific identity already exists in Drift, then their activity will be appended to the pre-existing contact record. If their identity is new to Drift, Drift will create a new contact record with an externalId set to the value passed in "your_unique_id_for_this_visitor" string as seen below. This value is an identification string you provide and should be unique and unguessable. Here's how this looks in Javascript:

drift.identify("your_unique_id_for_this_visitor",
  {
    email: "[email protected]",
    firstName: "John",
    lastName: "Doe"
  },
  { userJwt: jwt }     //optional, more info below
);

In most use cases, drift.identify() is used in conjunction with a site's login flow. After a visitor is authenticated and identified by your login flow, their unique userId is commonly passed as the unique id parameter in drift.identify(). Doing so will give the contact record a single id value that is consistent across your User database and Drift.

🚧
Important! In certain scenarios, the timing of when to call drift.identify()is extremely important and the general rule is to push site visitors to login as soon as possible. Take for example the following journey a user of your site might take. The first time the site visitor arrives on your site, they are anonymous and Drift assigns a drift_aidwith a unique value. The site visitor has a chat with Drift where they provide their email and telephone number. The site visitor then logs-in and via drift.identify()their contact record in Drift is given a unique externalIdand the current drift_aidis now associated with their contact record. The email and phone number are also captured on the correct contact record. The site visitor leaves and later returns to the site on a different browser. They're anonymous again because the original drift_aidis not present- Drift assigns their return visit a new drift_aid. They interact with Drift and provide their address. The site visitor then logs-in and via drift.identify()their contact record in Drift is retrieved by looking up the unique externalIdand the current drift_aidis now associated with their contact record. However, any data collected prior to drift.identify()during this second visit, will not be appended to the correct contact record in Drift. This happens when an anonymous visitor becomes known and they have a previously created contact record in Drift. Avoid this scenario by designing your playbooks to push anonymous site visitors to login (or register) as soon as possible in the playbook flow.

🚧
Important! The domain of your site's publicly accessible pages versus the login protected areas is important! Essentially, browsers are built to prevent different domains from reading cookies set by other domains. If your public website lives on http://publicsite.com but logged-in users are directed to http://publicsitemembersonly.com, the drift_aidcookie will not be carried with the site visitor after they log in and pass through the drift.identify()process. Consequently, any Drift activity prior to their login and redirect to http://publicsitemembersonly.com, will not be appended to their contact record in Drift. This is another reason why the general rule when using drift.identify()with a log-in process is to push the site visitor to log-in as soon as possible.

When a user logs out of your site

Implementing drift.identify() allows Drift to ingest data about your logged-in users, but what happens when they log out? With no action, the Drift cookie will persist and any activity in Drift will continue to be associated with the contact record of the formerly logged-in site visitor. In order to disassociate site activity with a logged-in user's record in Drift, a call to drift.reset() must be made during or immediately after the site visitor logs out. The reset method clears the Drift cookie and any subsequent Drift activity by the site visitor will be associated with a new, anonymous record in Drift.

When to use the server side endpoint?

The server side endpoint to create a contact record in Drift is most frequently used to 'pre-load' contact records into your instance of Drift during the onboarding process. Contacts should be created using the same userId that will be passed into the client-side function, drift.identify(), when a user logs into your site.

This endpoint is also useful to pass contact related information into Drift that may be useful for targeting or to chat agents when engaging in live chat with a signed-in user. For example, if a user recently made a purchase, this information can be appended to their contact record in Drift via a PATCH request that references the contact's unique externalId.

Track and setUserAttributes

Two additional client-side methods work closely with drift.identify()- drift.track() and drift.setUserAttributes(). When calling drift.identify(), Drift will update the contact record associated with the current drift_aid browser cookie. As described above, the drift_aid will only point to a specific contact record with an externalId set by your system if the drift_aid was previously associated with the correct record via a call to drift.identify(). Otherwise, events and attributes will be appended to a Drift contact with a randomly generated externalId.

What are JWT's and why would I want to use them?

JWT stands for JSON web token and they provide a layer of security you can optionally add when using drift.identify(). Including JWTs helps prevent a nefarious actor from guessing (or otherwise acquiring) the unique externalId assigned to a Drift contact. Without JWTs this person could use drift.identify() to convince Drift that they were the identity associated with the externalId. This could give them access to historical chats, and would allow them to set attributes and other information on someone else's contact record. More information on JWTs available here. Requiring JWTs when calling drift.identify() increases the complexity of implementing drift.identify() significantly as it requires additional server side scripting to generate tokens and pass them back to the front-end before calling drift.identify(). Be sure to budget additional time during setup if JWTs will be used.

Additional Info

Viewing a Contact's externalId

Drift does not expose the drift_aid or externalId values in the UI by default. These values can be passed into a custom contact attribute if desired to be displayed on the contact record in Drift. You can also verify a contact's information by inspecting the contact page while it loads and viewing the response from the GET request to https://customer.api.drift.com/end_users/<contactId>. A contact's attributes can also be retrieved via the GET Contact API endpoint.

In the above image the numbered highlights refer to:

The specific network request that retrieves this particular contact's information
The contact Id. This is a number assigned to the contact by Drift and used in URLs to reference this specific contact. You cannot set or edit this value in Drift.
The externalId. This value is set by the first parameter passed to drift.identify(). In the image, this contact's unique id as set via drift.identify() was "new_unique_user". If this contact was created without the use of drift.identify(), this value would be an unguessable Drift generated string.
The contact attributes that are displayed in the Drift UI. If you would like to see any contact attribute in the Drift UI (such as externalId or drift_aid) you must pass those values to this contact as custom attributes.

Why doesn't Drift prevent duplicate email addresses?

Drift does not prevent multiple contact records from having the same email address. But it does prevent duplicate records with the same externalId. The reasons for this are closely related to the drift_aid and the drift.identify() process.

Here's a scenario. User A is not honest. They arrive at your site and when asked for their email in the Drift chat they enter [email protected]. Drift has assigned User A a drift_aid and now associated that contact record with the email [email protected]. User A has multiple conversations in Drift and visits many pages across your site. A few days later User B visits your site. Drift assigns User B a new drift_aid and begins tracking their activity. Eventually User B adds their email address in the chat. If Drift prevented duplicates on email alone, User B, at this point the real User B, would either be blocked from entering their email or more likely, their record would be merged with the impersonated activity done by User A. Either outcome is not ideal. Drift chose to keep these two contact records separate rather than merging data between two unverified identities.

Using drift.identify() can alleviate this issue by leveraging your own site's authentication process to create a single, and persistent contact record when the site visitor passes through your login process. User A can still intentionally or unintentionally enter User B's email when asked and their activity while 'impersonating' User B will still be associated with a Drift contact record with an email of [email protected]. But when User B visits your site and you pass their unique identification string to Drift when they successfully log-in, you've now set User B's "real" contact record in Drift with a unique externalId (provided by your system). The drift_aid assigned to User B when they first arrived at your site is now also tied to the 'identified' Drift contact record. Activities will only be tracked to this contact record if the drift_aid in their browser has been associated with their externalId via a call to drift.identify().

TLDR: Drift intentionally does not prevent contact records with the same email address. To verify the identity of a site visitor, you should use your own authentication process coupled with drift.identify().

Contents