This new developer overview will contain all the key information and links required for you as a developer to test and configure HelloScreen Co-Browsing. It's a live document and will be updated regularly.
Contents
Co-browsing is software that gives an online support agent the ability to see what the customer sees, instantly and without downloads.
Not only that but agents can use their mouse on their customer’s screens to guide them.
They do this without the downloads that old school screen sharing requires and you typically begin a co-browsing session within seconds.
How does it work? How is it different to regular screen sharing?
Remember how old school screen sharing involves downloads….
Co-browsing involves pasting a few lines of javascript on your website and neither the agent or the customer ever need to install anything to screen share on that website.
Let's say a customer asks for help on your website. The support agent starts the co-browsing session with that customer. Upscope renders the web page the customer is looking at and makes it appear on the support agent's computer by passing the html, css and re-creating it for that agent.
This also allows for further interaction because rendering html and css allows Upscope to show the customer's mouse movements and send the agent's mouse cursor to appear on the customer's screen.
In addition, this makes it secure for the user. You can't see their messy desktop, only the browser tabs containing pages of your website with that javascript snippet.
Here's an interview with our CTO on how co-browsing technology works.
Getting started
Sign up and get your trial account
The simple way to install Upscope and try your first screen share is:
Add that javascript code to all pages on which you wish to screen share. You can paste it anywhere on the page.
Now go to https://app.upscope.io and you’ll see a list of your current users on any pages on which you placed the javascript code.
### Testing on your local or development environment
We proxy your websites CSS files so if your development environment is blocking the CSS file then the page will look wrong.
Here's what to do when that happens:
1. Go to your [Upscope settings.](https://app.upscope.io/settings/teams/_/co_browsing)
2. Enter your dev environment url into the **Connection settings** section as a wild card.
For example:
However, you don't want to do this for your main site as it would slow down the co-browsing experience. It's for testing only.
### Change the javascript to search for users by email and name
By default the list of users on https://app.upscope.io shows up as IP addresses and locations but you can make a user appear in the list as below and be able to search for them by name and email.
**How do you do this?**
Use the following function along with the default javascript snippet:
```javascript
Upscope('updateConnection', { identities: ['name', 'email'], // This can be a list of separate identities, a string with a single identity, or nulluniqueId: '123', // This can be a string or number uniquely identifying the user, or null});
```
Example:
```javascript
Upscope('updateConnection', { identities: ["Acme Technologies", "john@acme.com"]});
```
Note: In the above template code there's also a "uniqueId" option.
You can use this either on it's own or along with the list of identities. It might be **useful in identifying each customer by a unique number or string you prefer** to associate with them.
See [more on identifying a customer](/co-browsing-api/docs/javascript-sdk/identifying-the-visitor)
### Setup the pin code for customers who call in
There are several ways to begin screen sharing with customers who phone in.
When a customer phones you and needs help you could simply ask them for their name, email address, uniqueId or location and enter that into the Upscope search bar, assuming you've set up your javascript code to allow that.
The other way is to ask the customer for **their unique 4 digit code** that Upscope generates for each customer and which can be accessed via the Upscope javascript API and displayed on the page.
This Upscope generated code can be displayed to the customer a number of ways:
1. Using the Upscope widget. This is a very small box which sits on the bottom left or right hand side of the page and expands to show a 4 digit pin code when the customer hovers over it.
2. Ask the customer to press their CTRL key 5 times and a box will pop up to show them the 4 digit pin code.
3. Add the pin code to the footer of the page.
While you can set up the CTRL and widget within your Upscope settings, the instructions for adding it programmatically to the [footer of the page are here.](/co-browsing-api/docs/javascript-sdk/lookup-code)
Troubleshooting installation
----------------------------
Besides the CSS proxying issue we posted further above there are a couple of other issues you might run into in the early days.
### CSP rules on production
If you're having problems running Upscope on production then check the CSP rules. Upscope needs to run javascript code on your website and connect to our server. These are the Content Security Policy rules you'll need.
```
script-src 'self' https://code.upscope.io https://js.upscope.io;
connect-src wss://*.upscope.io https://*.upscope.io;
media-src https://js.upscope.io;child-src https://storage.upscope.io;
img-src https://app.upscope.io https://app-cdn.upscope.io;
```
### User not found
When you click on an individual user in the list on https://app.upscope.io or if you click on an Upscope screen sharing link within an integration you might, when you first install Upscope, see a 'User not found'.
Some of the most common reasons are below:
1. If the user is not found, it could be that they haven’t refreshed the page. Please get them to refresh it and then try again.
2. The second most common reason is that **they might be on a page, or have moved to a page, where the Upscope code is not installed.** Please contact your development team to confirm that the Upscope code is on that page. Alternatively, if you know how to access the developer console on that page, you can enter "Upscope" into the console and it will confirm if it exists or say not found.
If the code is on the page and refreshing does not work then please help us investigate by contacting us on our live chat and giving us a test username and password for the app which we can pass to our development team.
3rd party website browsing
--------------------------
Code-less co-browsing across 3rd party websites is available with Upscope. It's the most difficult technology to build and only a couple of companies have managed to do it! Upscope's codeless proxy browsing feature is currently in beta. You can access and test it now by enabling beta features within your settings once you've signed up and got started with Upscope.
Integrating Upscope Co-browsing
-------------------------------
Most people who sign up to install Upscope are either using HelloScreen Co-Browsing with a 3rd party live chat, CRM system, a phone system or with their own proprietary support system.
Fortunately there are ways to integrate with all of them.
### Upscope auto-integrates with some live chat systems
HelloScreen Co-Browsing was built to auto-integrate with several live chat and CRM systems.
Once you’ve copied and pasted the Upscope javascript code onto the same page as the live chat code, a screen share link appears in the live chat chat panel.
After install, please make sure you refresh the customer’s page and the agent’s live chat panel.
For other systems we'd require a few more steps so click [here for the full list of integrations and their installation instructions](https://help.upscope.io/en/collections/2779709-integrations-and-apis).
### Install marketplace apps for Intercom, Zendesk, Frontapp...
Some integrations are more advanced because we have a custom built app for that interface including additional features like screenshots and alternate permission flows.
For example, the Upscope Intercom app allows you to see screen shots of customer pages up until they opened live chat to make a request, which is useful for diagnosing problems without asking too many questions.
We have custom apps for Intercom, Zendesk, Frontapp, LiveChat at the time of writing.
If we do have a custom app you'd need to **install both the Upscope javascript snippet and install the Upscope app** from their marketplace.
### Integration not listed? Contact us or go ahead and create it
If you are using a support system which is not listed in [our help section](https://help.upscope.io/en/collections/2779709-integrations-and-apis) then it might be possible to create a new integration. Sometimes this can be done in minutes.
You can either contact our team to look into it or even build that integration yourself.
Below is an example of how to do it with a live chat system.
Typically an integration **requires that the live chat system allow custom attributes** so that we can add a new Upscope screen share attribute to that agent's view of the live chat interface.
If it allows custom attributes then you can generate an Upscope screen share link and pass it as a value to that custom attribute.
For example, below is an integration we did with Trengo live chat.
Within the Trengo interface we created a custom attribute (field\_id: 90590) and we passed our Upscope screen sharing link as the value of that field\_id within the Trengo on\_ready function.
So when Trengo loads on the page for a customer, Upscope generates a unique screen sharing link and passes that into Trengo. Once the customer asks for help and the agent opens the chat box, they'll see that screen sharing link appear in the Trengo interface.
```javascript
window.Trengo.on_ready = function() {
Upscope('getWatchLink', function(link) {
window.Trengo.contact_data = {
custom_fields: [{
field_id: 90590,
value: link
}]
};
});
};
```
Below you can see the Screenshare link on the right hand side.
See the full help page on the [Trengo integration](https://help.upscope.io/en/articles/5107837-trengo-integration) as an example.
If there's a live chat service we don't integrate with then the above is one method of creating that integration. Alternatively contact our team and we'll look into it for you.
### Add the co-browsing iframe onto your system
If your live chat, CRM or custom built system allows embedding of iframes you can screen share directly from within that system by embedding Upscope.
At present, when a support agent clicks the Upscope screen sharing link, it will open up a new tab under the Upscope domain to allow you to screen share. You might not wish to do that. You can instead embed the Upscope screen sharing session directly within your system.
How?
Using the custom embed url.
Integrate Upscope into your live chat or CRM by adding an iframe and pointing it to , which is a slimmed down version of the Upscope app. This requires no API skills, it's as simple as pointing the iframe to that url.
### Phone support integrations
Fortunately you would not need an integration into a phone system because it's done via the auto-generated Upscope phone support code.
Upscope can generate a phone support code for customers and you can use that to find that customer's screen and begin screen sharing.
Typically it involves enabling the option for the customer to click the CTRL button 5 times resulting in a 4 digit code appearing for that customer to read out to the agent.
The agent would enter that code into the Upscope search bar to find the customer's screen and begin the screen sharing session.
Read about the [Upscope phone support code here.](/co-browsing-api/docs/javascript-sdk/lookup-code)
Enable and test additional features
-----------------------------------
### Agent request
You can add a button which enables a customer to request help from an agent in one click.
This is done via the **agent request button** which can be enabled from your settings.
See how to [enable and use the agent request button here.](https://help.upscope.io/en/articles/2801566-let-your-customers-request-a-session-agent-request-button)
If you want to **build your own interface for requesting an agent** then [read the following.](https://help.upscope.io/en/articles/2809804-how-to-request-an-agent-programmatically)
### Personal co-browsing link
You can now start a screen share for a scheduled meeting by having Upscope notify you that the customer has arrived on the site.
You can do this by giving the customer your personal co-browsing link to click when the meeting starts. You'll get notified they're on the site.
You can edit the co-browsing link url in your settings but it has to be unique of course.
Read [more about it here.](https://app.intercom.com/a/apps/jjuq5mvv/articles/articles/2444107/show)
The Javascript API is a default requirement
-------------------------------------------
Everybody using Upscope will use the [default javascript API](/co-browsing-api/docs/javascript-sdk) as this is the snippet that's added to the page to allow co-browsing.
Besides adding the javascript snippet to the page, why else would you need to look through the javascript API docs? To customize co-browsing for the user and agent.
Within your Upscope javascript snippet you have the *Upscope('init')*.
The *Upscope('init)* is used to both initialize the code and pass in configuration attributes.
This includes:
1. Pass in identities and tags to help you find or sort users.
2. Change the default customer authorization prompt.
3. Change the message that appears when a screen share ends.
4. Allow agents to see the remote console.
5. Allow agents to remote click, scroll, type.
*Upscope('init')* also contains functions.
This includes:
1. Update a connection to update user information.
2. Get the watchlink (aka the screen sharing link) to display it.
3. Get the phone support look up code to display it anywhere on your site.
4. Request agent or cancel request agent functions.
5. Upscope 'on' is used to listen to events such as when a screen sharing session starts, when screen sharing ends, when the user is waiting for an agent.
See the full [co-browsing javascript api docs here.](/co-browsing-api/docs/)
Upscope REST API integration and white labelling
------------------------------------------------
Typically the [REST API](/co-browsing-api/docs/rest-api) is used for handling authentication however you wish.
Rather than having your support agents create an account on Upscope you can instead manage all authentication yourselves.
### Getting started with the REST API
The Upscope team can enable the REST API for your team once you request it.
This will then give you the secret API key you'll need to pass in as a header when accessing the API.
As you can see within the [REST API docs](/co-browsing-api/docs/rest-api) you can do following:
1. Authenticate agents
2. Generate a link to start screen sharing
3. Search for visitors
4. Retrieve a list of visitors
5. Get customer screenshots
6. Retrieve usage statistics
7. Delete visitor data
Here's a broad [overview of adding co-browsing to your proprietary platform.](/blog/integrate-co-browsing-into-your-platform-and-offer-your-users-something-unique/)
See an example of white labelling and [integrating Upscope into your platform for YOUR clients to use with their customers.](https://help.upscope.io/en/articles/3280575-how-to-white-label-upscope-and-integrate-it-into-your-platform-for-1000s-of-your-clients-and-their-respective-support-agents)
See [the REST API docs here.](/co-browsing-api/docs/rest-api)
On-premise
----------
When your data protection policies don't callow customer data to leave your infrastructure you can deploy Upscope on-premise.
There are a number of options for implementing on-premise depending on which part is essential to control.
Options include:
1. Data service on premise + Upscope cloud
2. Data service on premise + Upscope API
3. Data service on premise only
See [more about our on-premise offering here.](/co-browsing-api/docs/on-premise)
Security and controlling data
-----------------------------
### Element masking
Element masking can be used on fields or blocks where the customer has data you don't wish agents to see for security, legal or privacy reasons.
You can add masking via your Upscope settings or programmatically.
Within your [Upscope settings](https://app.upscope.io/settings/teams/_/co_browsing) you can add a comma separated list of elements you want to hide.
Alternatively just add a 'no-upscope' class to the input or element directly.
See [more on hiding data from the agent's screen.](/co-browsing-api/docs/javascript-sdk/element-masking)
### Passing your companies security requirements
Upscope works with health, banking and other SaaS companies with stringent requirements for data and security.
See [our security overview here.](https://upscope.com/security/)
Upscope is ISO27001 certified and is also undergoing SOC2 certification.
### Protecting user data
While Upscope's javascript snippet is on your site it does not go through Upscope servers until screen sharing is initiated and even then there's minimal storage and retention of data, typically only meta data.
We've broken down the data that is sent to Upscope for processing, wether it is cached or stored, and for how long.
See [the full breakdown here.](https://help.upscope.io/en/articles/1957880-what-data-does-upscope-store)
### Regional servers and data sovereignty
For situations where you need to make sure data stays within a country or region you can choose where data is stored and processed.
The Upscope architecture allows you to choose one of our regional servers including regional data storage and processing. There are servers in the USA, Canada, South America, Europe and Asia. You can choose a region within your Upscope settings.
Presentation docs to ease adoption of co-browsing
-------------------------------------------------
We'll soon be adding a full set of documents here to pass to your key decision makers, support team managers, security officers and more. These will help in getting others to understand and adopt co-browsing.
### For security officers
See an [overview of Upscope's security measures here.](https://upscope.com/wp-content/uploads/2021/04/Security-Doc-April-2021-2.pdf)
See [the data Upscope process and stores.](https://help.upscope.io/en/articles/1957880-what-data-does-upscope-store)
### For key decision makers
Coming soon...
### Make it easy to onboard team members
Coming soon...
Engineering blog
-----------------
We're running ongoing interviews with key devs and we'll post links to them in this section.
How [was HelloScreen Co-Browsing built](/blog/rather-than-open-source-cobrowsing-so-this-is-how-we-built-our-own/)
The [Upscope Ruby Rails Intercom integration](/blog/intercom-api-ruby/)
