Identifying the Visitor

You'll need to identify users in order to search for them on the UserView application. For more information, see Searching for Customers.

Here you can see you're able to search using Jack's email address, this is because the identity has been passed through UserView's code.

UserView Screenshot

If you'd like to see customer data (email address, name, unique id, etc.) on UserView, there may be some additional steps. If you use Intercom and Zendesk, we try to use their API to automatically display it for you, but if you don't, you'll only be able to see IP addresses.

Identifying Visitors on UserView

There are several ways to identify the visitor on UserView.

Providing Identity Information

Regardless of whether you have the identity information at page load or later on, we encourage you to call Upscope('init'); as soon as possible so there is no delay in the continuation of an active session.

At Page Load

In a Single Page Application (SPA), you can provide the details right with the Upscope('init'); function if you have them from your backend.

// Rest of the installation code...
Upscope('init', {
  identities: ['John Smith', 'acme.com'],
  uniqueId: '00032'
});

Visitor Information Details

You can provide the following bits of visitor information:

Key	Type	Description
`identities`	String[]	An array of strings with whatever identifying information you want to send us.
`uniqueId`	String	A string with a unique id of the visitor from your database. This could be the visitor’s email address.
`tags`	String[], each matching `/^#[A-Z-]+$/`	An array of hashtags to filter visitors by.
`integrationIds`	String[], each matching `/^[a-z]{3,}:.+$/`	An array of strings representing an integration name and an integration id. For example, if your app is called acmechat, and the acmechat ID for the visitor is `123`, you could pass `["acmechat:123"]`.

Removing Pieces of Identification

Any piece of identification set to undefined will be ignored. This means that if you identify visitors on the /login page, and they navigate to another area of your site that doesn’t have identification, we will keep the data we already have. If you want to remove any piece of data, you’ll need to set it to null.

Example

First page load on login screen…

Upscope('init', { identities: null });
// Visitor's identities will be null

Second page load, visitor is now authenticated…

Upscope('init', { identities: ['John'] });
// Visitor's identities will be ['John']

Third page load to area that doesn’t require authentication…

Upscope('init');
// Visitor's identities will be ['John']

Fourth page load after clicking logout…

Upscope('init', { identities: null });
// Visitor's identities will be null

If you set a uniqueId to null or to a different value after it was already set, UserView will reset the connection and create a new visitor as we’ll assume that they are now a different person. This will not happen if a session is currently ongoing.

Logging the Visitor Out

You can log the visitor out by calling Upscope('reset');. This will also reset the connection and create a new visitor with a new ID.

Using the Watch Link

The most reliable way to identify a visitor is to use the watch link. This is a unique link to the particular browser the visitor is using, generated for each visitor.

Browser or Visitor?

Although we use the concept of "visitor" throughout the docs, we really mean the visitor's session. If the same person logs in on two different browsers, and you initiate UserView each time with the same uniqueId, you'll end up with two separate visitors in UserView.

Each watch link looks like this: https://upscope.io/w/SHORT_ID.

We automatically add the watch link to most of our built-in integrations, but if you are building your own, you can retrieve the id by using the following:

Upscope('getWatchLink', link => {
  console.log(link);
});

Authentication

The watch link is not meant to be secret. You can freely share it around, as it will still require the agent to authenticate on UserView's dashboard to be used. If you want to use the link without authentication (or without the agent having a UserView account), you'll need to exchange it with a secure one through the REST API.

Need Only the Short ID?

If you only need the UserView Short ID for an integration, you can retrieve that by doing:

Upscope('getShortId', shortId => {
  console.log(shortId);
});

Documentation