Login Get Started
Products
Docs Menu
Menu

REST Integration Flow

Although our API supports many different ways of integrating Upscope, the most common use case is to allow someone (a "Viewer") to see a browser tab of someone else (a "Sharer").

The easiest way to choose who should be the Viewer and who should be the Sharer is to determine:

  1. Who should have the most "natural" experience when interacting with the page: the Sharer, ideally.

  2. Who should be limited in what they can do on the page, like viewing, scrolling, etc: the Viewer, ideally.

  3. Who should be able to keep viewing the page after the Session has terminated: the Sharer.

As far as Upscope is concerned, the Sharer is actually the Visitor, and the Viewer will be the Agent. There can be more than one Agent in the same Session.

In most deployments, the Agent / Visitor terminology will make sense, but you might decide that for your use case, it makes more sense to reverse the roles, and your employee be the Visitor, and the end customer be the Agent.

1. Setting up the Visitor

The first step to creating a Session is to make sure the Visitor is set up and on the page you want to Share.

You can either install the code on a page, or by creating a Universal proxy session.

Installing the code is ideal in a situation where you control the pages or website being shared.

All you need to do is install the Javascript SDK on the pages you want shared.

If you are unable to install Upscope on the pages you want to co-browse on, you'll need to start a Proxy session.

Create a new endpoint https://yoursite.com/visitor on your server.

When called, your server should make a request to our REST API to initiate a Proxy session and redirect the Visitor to the URL we give you.

You can open this endpoint in an iframe if you wish.


2. Identifying the Visitor

To properly connect the Visitor and the Agent, you'll need to know who the Visitor is.

You can either use an ID we give you, or give us one. You could for instance generate a unique ID for each Session, or you might already have an ID in your database if you are enabling a logged in user ↔ logged in user co-browsing experience.

If you have the code installed, you can:

  • Get the Upscope Short ID through Upscope('getShortId') and save it to your own database (or somehow give it to the Agent side).

  • Use your own ID by passing it as uniqueId.

  • Use the lookup code.

If you are using the Universal proxy, you have two options:

  • Set your own uniqueId by adding ?___upscope_unique_id=UNIQUEID to the query string of the initial_url.

  • Use the lookup code.

3. Starting the Session

On the Agent side, with the Upscope Short ID or your own Visitor ID on hand, you'll be able to start a Session.

To start a Session, create an endpoint like https://yoursite.com/agent?visitorid=THEID_HERE on your server.

When called, the endpoint should call the start session endpoint and provide it with a name and an ID of the Agent.

It will receive a watch_url that the Agent's browser should be redirected to. All this should happen within a single request, and the watch_url should not be stored anywhere.

Using your own unique ID?

If you are using your own unique ID you'll need to convert it to an Upscope Short ID before creating a Session.

You can do this by searching for id:YOUR_OWN_UNIQUE_ID, and using the first Visitor's short_id.

4. All done!

This should be enough to kick-start your integration. There are a lot of options you can customize to make the experience more in line with your branding.

If you need any help, please get in touch.