Identifying the Visitor

There are several ways to identify the visitor on Upscope.

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.

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'
});

You can call Upscope('init'); first, then provide the identity information with Upscope('updateConnection');.

// Rest of the installation code...
Upscope('init');
// getVisitorInfo is a made up function you might have in your code that gives you visitor information
getVisitorInfo().then(visitor => {
  Upscope('updateConnection', {
    identities: [visitor.name],
    uniqueId: visitor.id
  });
});

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 Identification

Any piece of identification set to undefined will be ignored. 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. To remove any piece of data, 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, Upscope 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.

Keeping the Connection Secure

To ensure that a particular visitor is only associated with one browser, you can set a secretKey during initiation. This will require that the same secretKey be set for all further connections. If the secretKey is missing or is different, a new visitor with a new shortId will be created.

This prevents an attack where a malicious actor, who has access to the shortId belonging to someone they want to co-browse with, is able to open a connection with their same id and accept the co-browsing request on the user's behalf.

Getting the Short ID

If you need the Upscope Short ID for an integration, you can retrieve it by doing:

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

Using the Lookup Code

Learn more about the lookup code on the dedicated page.

Documentation