NAV

General Usage

The CoBrowse Giosgapp should be setup properly for the client before it can be used. At the moment the steps include:

Install the CoBrowse app from the service console

No additional details.

Make sure the configuration fields match the following:

Application url
https://api.giosgcobrowse.com/apps/sessionapp/

Visitor assets url
https://api.giosgcobrowse.com/static/visitor/cobrowse.loader.js

Initialization command
See below

Autoload visitor assets
Either enabled (autoload) or disabled (rule based load)

Enable CoBrowse on the client site.

There are two ways in which the CoBrowse could be enabled on a client site:

First you should make sure that the autoload visitor assets option in the app configuration is disabled.

Then create a rule for the target site with the following parameters:

(1) Select the domain/room for which the rule will be applied (or enabled “all rooms” in the config)

(2) Give your rule the name “CoBrowse Loader” and enable it

(3) No conditions needed (but you can add you want)

(4) Action Advanced - Run a custom JavaScript

(5) Paste the following code

// Here is your CoBrowse config
window.giosgCoBrowse={ui: false}

// Here we run the cobrowse loader
var s = document.createElement('script');
s.src = 'https://api.giosgcobrowse.com/static/visitor/cobrowse.loader.js';
s.onload = function(){console.log("CoBrowse load success!")}
document.body.appendChild(s);

In rule based load the window.giosgCoBrowse variable hosts the configuration options. For examples of common CoBrowse configuration options see below.

2. Installed app autoload

To automatically load CoBrowse for all domains/rooms without using the rule engine, enable the Autoload visitor assets option in the app configuration.

Paste the CoBrowse config in the Initialization command field:

Initialization command
window.giosgCoBrowse={ui: false}

With this configuration the application assets are loaded for every domain associated with the Giosg client. This might lead to performance issues and increased page load time.

Common configuration options

If you use rule based load, replace the line window.giosgCoBrowse={...} with any of the following.

With installed app autoload you have to change the initialization command field to any of the following.

No UI

window.giosgCoBrowse = {ui: false}

UI but no launch button

window.giosgCoBrowse = {ui: true, widgets: {launchButton: false}}

Set top position of launch button

window.giosgCoBrowse = {ui: true, widgets: {launchButton: true, top: '75%'}}

Setting language to finnish

window.giosgCoBrowse = {widgets: {lang: 'fi'}}

Set input fields as protected

window.giosgCoBrowse = {protected: ['input#id_of_input', 'input.class_of_protected']}

Note: You need to find a valid CSS selector for the input you want to protect. You could use web inspector to do this.

Styling the widgets

To add custom styling to the CoBrowse widgets such as launch button, pin dialog and active top header you will need to supply your own stylesheet to override the default CSS.

Visit the GitHub repository for examples.

Access token authorization

Giosg uses JSON Web Tokens to authorize access to certain API endpoints and real-time messaging channels.

This access token based authorization is especially used in cases where the authorizing service does not have access to the PostgreSQL database for determining permissions for the user.

Authorization happens in the following steps:

  1. The client retrieves the JWT access token from service.giosg.com. The exact API endpoint depends on the context.
  2. The client makes the request to an external service, providing the JWT access token in the Authorization HTTP header. The service checks the validity of the token.

Authorization with access tokens

Example authorization header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.we2snuuhq-cnPk-GMJVoBhyZ7ZKPa95Qxe_3VkEaf_E

Authorization is done by sending the JWT token with the HTTP header:

Authorization: Bearer <token>

Access token structure

Header

Example of access token header

{
    "alg": "HS256",
    "typ": "JWT"
}

Algorithm used for access token generation and verification is always HS256

Payload

Example JSON Web Token payload

{
    "jti": "f1f6e824-6b1c-4ac4-ab99-d33187ba4555",
    "exp": 1456229945,
    "iat": 1456143545,
    "version": 1,
    "iss": "https://service.giosg.com/api/v5/login",
    "aud": [
        "service.giosg.com",
        "messagerouter.giosg.com"
    ],
    "scopes": [
        "/api/v5/orgs/9472c2c6-c86e-4aff-ab01-682b3c31cecf/users/6d4967f7-7c4c-492f-b765-299fa99ebae5/chats",
        "/api/v5/orgs/9472c2c6-c86e-4aff-ab01-682b3c31cecf/users/6d4967f7-7c4c-492f-b765-299fa99ebae5/chats/*/messages"
    ],
    "user_id": "fff3d494-97ba-470f-ba92-45572c70133d",
    "organization_id": "e5c33af6-ef18-4d3a-b87b-4a8548c42f7b",
    "app_id": "a9081f31-3cef-42f3-8791-f404327eba98"
}

The access token is a signed JSON Web Token. Here’s the complete list of attributes that the JSON Web Token may contain.

Attribute Type Required Description
jti string Required JWT ID: a unique identifier for the access token
exp integer Required JWT Expiration Time as a Unix timestamp
iat integer Required JWT Issued At as a Unix timestamp
iss string Required JWT Issuer: the full URL of the endpoint from which this token was originally retrieved
aud array of strings Required JWT Audience: only these host names should accept the access token. The names should not include scheme or port numbers.
version integer Required Version number of the token. Must be 1. Anything else is currently considered invalid.
scopes array of strings Required List of endpoint permission patterns, describing which endpoints should be authorized. This is the preferred way for authorizing an endpoint access.
user_id ID Optional The permission is granted for this specific user. Omitted if the permission is not user-related. If present, the organization_id should also be present, because user ID “belongs” to exactly one organization. Avoid using this for authorization! Use scopes instead.
visitor_id string Optional The permission is granted for this specific visitor. Omitted if the permission is not visitor-related. If present, the organization_id should also be present, because visitor ID “belongs” to exactly one organization. Avoid using this for authorization! Use scopes instead.
organization_id ID Optional The permission is granted for this organization. If present without user_id or visitor_id, it indicates a organization-wide access. Avoid using this for authorization! Use scopes instead.
app_id ID Optional The permission is granted for this specific Giosg APP. Avoid using this for authorization! Use scopes instead.

Avoid using user_id, visitor_id, organization_id, and app_id for authorization checks! They exist to describe to whom the access was granted, not what the receiver is allowed to do. For example, a reseller may receive an access token to resources on another organization or user. In this case, scopes describe which resources can be accessed with this token, but user_id just describes the person who is accessing the resources.

Endpoint permission patterns

Examples of valid permission patterns

[
    "/api/v5/resources/3479ffa5-ea58-45e8/examples/fc3caa06-4bff-4e6b",
    "/api/v5/resources/*/examples/fc3caa06-4bff-4e6b",
    "GET /api/v5/resources/371ff68b-aa10-486a/examples/*",
    "GET/POST/PUT /api/v5/resources/13f86308-7c49-4000",
    "* /api/v5/examples/*"
]

This section describes the exact procedure that must be followed when checking if the access should be authorized for a HTTP request with an access token containing scopes.

The access should be authorized if and only if there is at least one pattern in the scopes list that matches the request method and the requested endpoint URL path, as described below.

A permission pattern can have either one of the following formats:

In other words, the pattern may start with one or more upper-case request method verbs separated by a slash / (<METHODS>), and followed by a single whitespace. The rest of the pattern (<path>) is then matched against the endpoint path.

The pattern matches only if both of the following conditions are true:

When matching the request method, always consider HEAD requests as GET, and PATCH requests as PUT. Therefore, whenever the permission states GET it also implicitly allows HEAD. Same for PUT and PATCH, accordingly.

Instead of listing one or more methods, the permission may only state a single asterix * character as a method. This authorizes any request method verb to the endpoint.

The pattern path matches the requested URL path if and only if the following is true: all slash / separated components in the pattern, excluding any single wildcard character *, equal to the corresponding components in the URL path.

In other words, a single wildcard character (*) in a pattern matches any sequence of non-slash (/) characters. This is especially important to note if the wildcard is the final character in the pattern.

For example:

For path matching, any trailing slash (/) in the requested URL path should be ignored. For example, /foo/bar in pattern would authorize access to /foo/bar/.

For the best practice, all the patterns in access tokens:

Authorization errors

The service should return with the following status codes if the authorization fails:

Situation Status code Response
No authorization header provided 401 {"detail": "Authentication credentials were not provided."}
Token or its signature is invalid 401 {"detail": "Authorization token is invalid."}
Token is valid, but its contents are unknown to the service 403 {"detail": "You are not authorized for this action."}
The endpoint path does not match any permission listed pattern 403 {"detail": "You do not have permissions to this endpoint."}

Accept Header

You also need to define that you accept JSON-formatted responses by providing the Accept HTTP header:

Accept: application/json

Alternatively, if you are unable to customize headers, you may add format=json GET parameter.

Resource identifiers

Unless stated otherwise, all the resources in the system are identified with a Universally Unique Identifier (UUID). It is always represented as a string ID, in lower case and including dashes.

For example: 9ae65e7d-56c5-11e5-af8d-6c4008c08dfe

Paginated collections

An example of a JSON response with a paginated collection

{
  "next": "https://service.giosg.com/api/v5/examples?cursor=da965a3ea0164c8ab8baef1d4654e2d3",
  "previous": null,
  "results": [
    {"name": "Example Resource 1"},
    {"name": "Example Resource 2"},
    {"name": "Example Resource 3"},
    {"name": "Example Resource 4"},
    {"name": "Example Resource 5"}
  ]
}

Some of the API endpoints return paginated collections. That means that for large collections of resources, not all resources are returned in a single response, but the response contains an URL that can be used to fetch the next chunk (page) of results.

Paginated collections are objects with the following attributes.

Attribute Type Description
next string Full URL for requesting the next page. This is null if the current page is the last page.
previous string Full URL for requesting the previous page. This is null if the current page is the first page
results array of objects The list containing the result resources for the current page. Each item is an object whose attributes depend on the returned resource type.

Ordering collections

A paginated collection can usually be ordered by using an ordering attribute.

The allowed sorting criteria depends on the endpoint, but the basic usage is always the same. You have an allowed set of sorting attributes, e.g. first_name, last_name and created_at. You may then choose the primary sorting key and any secondary sorting keys with a comma-separated string, e.g. last_name,first_name.

Any sorting order is ascending by default, but may be reverted to descending order by prefixing with a minus (-) character, e.g. -created_at or last_name,-created_at.

Date/time format

Unless stated otherwise, all the date/times returned by API endpoints are ISO-8601 strings with format YYYY-MM-DDTHH:MM:SS.MSSZ, for example: 2015-08-31T16:32:17.879Z. Also, any date/time URL parameters or attributes send as a request payload accept this same format.

Unless stated otherwise, the times are expressed in UTC timezone!

CoBrowse Session API

Session

A cobrowse session object contains the following attributes.

Attribute Type Editable Description
id ID read-only The unique identifier of this team
instance ID read-only ID of the instance who owns this session.
pincode string optional Pincode which visitor can use for joining to the session.
start_time date/time read-only When the session was created
end_time date/time read-only When the session was closed

Creating a session

Create a session for an instance

POST https://api.giosgcobrowse.com/api/v1/instance/<instance_id>/session/

Session metadata

Sessions can contain key/value metadata.

Attribute Type Editable Description
id ID read-only The unique identifier of this team
timestamp ID read-only When the metadata was created or updated.
key string required Metadata key
value string required Metadata value

Create or update metadata

You may create or update the key/value metadata that belongs to an session (<session_id>).

POST https://api.giosgcobrowse.com/api/v1/instance/<instance_id>/session/metadata/<session_id>/

Delete metadata

You may delete metadata by making a DELETE request. This API allows you to delete one key or all keys.

DELETE https://api.giosgcobrowse.com/api/v1/instance/<instance_id>/session/metadata/<session_id>/

DELETE https://api.giosgcobrowse.com/api/v1/instance/<instance_id>/session/metadata/<session_id>/<key>/

Time Series Reporting API

General time series usage

All the API endpoints described in this section require some GET parameters defining the time range and stats aggregation interval. You may also define define optional GET parameters to localize and filter the results. The optional GET parameters are described per API endpoint.

The following table describes the GET parameters accepted by all of the reporting stats API endpoints.

Parameter Format Default Description
start_time date/time Required. Only return statistics after this moment (inclusive)
end_time date/time Required. Only return statistics before this moment (exclusive)
timezone string UTC A timezone in which params and results are expressed.
utc_offset string An alternative to the timezone parameter: the timezone expressed in static UTC offset, in hours.
time_interval string Required. Get results by selected time interval. Allowed values are 15min, 1h, 1d.

The chosen start and end date/time should be divisible by the chosen time interval. For example, if time interval is 1d then the time part of a start/end date should be exactly 00:00:00. For example: 201502-10T00:00:00. On the other hand, if time interval is 1h, then the hour part can be anything but the minutes and seconds must be 00. Also, if the time interval is 15min, then the minutes part must be either 00, 15, 30 or 45.

Please note that end time is exclusive, that is, the time slot that starts exactly on that moment is not included in the final results. Therefore, in order to get daily stats for 2015-03-05 and 2015-03-06, you should define the start time as 2015-03-05T00:00:00 and end time as 2015-03-07T00:00:00 (the beginning of the next day).

The optional timezone parameter may be provided as one of the tz database timezone names. This timezone describes the “local time” on which the API operates. For example: timezone=Europe%2FHelsinki would indicate timezone Europe/Helsinki.

You may alternatively use utc_offset parameter which, if provided, must start with either + or - and have two digit offset hour (zero-padded). This describes the offset from the UTC time, in full hours. If timezone or UTC offset is omitted, they default to the UTC time. An example parameter would be: utc_offset=+02

If a local time is defined, with either timezone or utc_offset, the given start_time and end_time are supposed to be expressed in this “local time”. Otherwise, we assume that times are in UTC.

Defining a local time is especially important if you are aggregating daily statistics, i.e. time_interval is 1d. The timezone is used to determine when each day starts and ends.

Every time series endpoint returns a JSON object with an item results, containing an array of aggregated timeslot objects. Each object has the attributes described by the following table. The items are in their time order. There will be a time slot for each time interval in the defined range, even if all the numbers would be zeros.

See the following sections for details.

Time series range limitations

The selected time interval defines the maximum time range between the start and end time. Also, the chosen time interval determines how far in the past the start time can be. These restrictions are described in the following table:

Time interval Max. time range Oldest possible start time
1d 100 days (No limit)
1h 7 days (168h) Any of last 140 days
15min 3 days (72h) Any of last 33 days

If the time range is longer than the maximum allowed range, or starts too early, then the server responds with 400 Bad Request error response.

Session statistics time series

You can get the time-based aggregated session statistics by making a GET request:

GET https://api.giosgcobrowse.com/api/v1/instance/<instance_id>/reports/sessionstats/timeseries

You may define these optional GET parameters to localize and filter the session stats aggregation results.

Parameter Format Default Description
meta_<key> string Only statistics about sessions containing these key/value pairs.
`group_by_meta_key string Group statistics using this key.
{
  "results": [
    {
      "start_time": "2015-03-07T15:00:00",
      "total_sessions": 135,
      "desktop_sessions": 85,
      "mobile_sessions": 30,
      "tablet_sessions": 20
    },
    {
      "start_time": "2015-03-07T16:00:00",
      "total_sessions": 137,
      "desktop_sessions": 84,
      "mobile_sessions": 32,
      "tablet_sessions": 21
    },
    {
      "start_time": "2015-03-07T17:00:00",
      "total_sessions": 130,
      "desktop_sessions": 82,
      "mobile_sessions": 29,
      "tablet_sessions": 19
    }
  ]
}
Attribute Format Description
start_time date/time The starting time of this aggregation. Its duration is equal to the selected time interval, e.g. 1 hour. This time is in the “local” time if a timezone is defined, otherwise it is in UTC.
total_sessions integer Total number of sessions on this timeslot
desktop_sessions integer Number of desktop sessions on this timeslot
mobile_sessions integer Number of mobile sessions on this timeslot
tablet_sessions integer Number of tablet sessions on this timeslot

Session Reporting API

Session

A session object contains the following attributes.

Attribute Type Editable Description
id ID read-only The unique identifier of this team
organization_id ID read-only ID of the organization who owns this team.
organization object read-only The organization who owns this team.
name string required Name of the team. Must be a non-empty string.
display_name string read-only Display name of the team. It may equal to the name attribute, unless this team is [shared][outgoing team share] to your organization with a custom share_name.
created_at date/time read-only When the team resource was created
updated_at date/time read-only When the team resource was updated last time
member_count integer read-only Number of members in this team, including both admins and non-admins. Available only to your own organization.
admin_count integer read-only Number of admins in this team. Available only to your own organization.

Get a collection of sessions

Return a paginated collection of all the team resources of an organization (<organization_id>). By default, this also includes any [teams shared to your company][incoming team shares]!

GET https://api.giosgcobrowse.com/api/v1/instance/<instance_id>/reports/sessions/

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at
is_shared boolean (none) If true, return only teams that are shared to the organization. If false, return only the organization’s own teams.

Teams are readable by anyone in the same organization. However, they can be created, updated or deleted only by organization users with users permission.

Retrieve team details

Get a single team object (<team_id>) of an organization (<organization_id>). This may be a [team shared to the organization][incoming team shares].

GET https://api.giosgcobrowse.com/api/v1/instance/<instance_id>/reports/sessions

Creating a team

Create a team for an organization (<organization_id>)

POST https://service.giosg.com/api/v5/orgs/<organization_id>/teams

Update a team

You may update the editable attributes of a team (<team_id>) that belongs to an organization (<organization_id>). You can make either a PATCH request (update a subset of attributes) or POST request (update all the attributes).

PUT https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>

PATCH https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>

Delete a team

You may delete one of your own teams by making a DELETE request.

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>

Team memberships

A team membership represents a user belonging to a specific team. Team memberships are only visible for teams of your own organization. A team membership resource has the following attributes.

Attribute Type Editable Description
team_id ID read-only ID of the team to which this member belongs.
team object read-only The team to which this member belongs, with attributes id, name, display_name, and organization_id.
user_id ID read-only ID of the member user.
user object read-only The member user resource. Has all other attributes than organization
is_admin boolean required Whether or not the member is an admin of the team.
created_at date/time read-only When the membership resource was created
updated_at date/time read-only When the membership resource was updated last time

Team memberships are readable by any member of the same organization. However, they can be created, updated or deleted only by either organization users with users permission. Otherwise, the endpoints will return a 403 Forbidden response.

Get a collection of team members

Return a paginated collection of all the team membership resources for a specific team.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships

Parameter Type Default Description
is_admin boolean (none) If true, return only admin memberships. If false, return only non-admin memberships.

Add a member to a team

You may add a user of your own organization to one of your teams by creating a team membership object.

POST https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

This returns a 201 Created response if the user with the given ID was successfully added to the team. If the user was already in the team, this updates the is_admin attribute and returns 200 OK response with the existing membership resource.

Update a team membership

You may update a team membership, i.e. change the admin status of a member either by attempting to create a new membership with POST or updating with PUT.

PUT https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

This returns a 201 Created response if the user did not belong to team previously but was now added. If the user was already in the team, this updates the attributes and returns 200 OK response with the existing membership resource.

You may also update a membership with a PATCH request, but this will return 404 Not Found in case the membership did not exist.

Remove a member from a team

You may remove a user from a team by deleting his/her membership.

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

Retrieve team membership details

You may get the a user membership resource in a team:

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

Javascript API

Visitor object

The coBrowseVisitor object is a self-contained client-side instance that handles everything from loading of additional libraries to pin dialog initialization, messagerouter communications and DOM mirroring.

Initialization

The instance accepts the following initialization parameters:

Parameter Type Default Description
config object {} Configuration options as JSON object
var cobrowse = new coBrowseVisitor({});
cobrowse.init();

Configuration options

The only initialization parameter of the coBrowseVisitor object is config, which accepts a JSON-style configuration. This parameter can override any existing configuration property on the cobrowse object.

var cobrowse = new coBrowseVisitor({
    highlightClassName: 'overriding-this-property'
});

Example: Override the CSS class name for highlighted elements with the string provided. In this case it’s not particularly useful but works as an example.

Useful configuration options:

Option Type Default Description
environment  string dev  Environment can either be "dev" or "production" and it affects mostly urls and loading behavior
ui bool true Set to false if the visitor pin dialog UI should not be initialized along with the visitor object
passwords bool false Protect password type input fields so that no sensitive data is neither transmitted nor displayed to the agent
protected array List of element selectors that should be similarly protected
nodeHost string Messagerouter endpoint url
baseHost  string Generic API endpoint url

Example: Protecting input fields

var cobrowse = new coBrowseVisitor({protected: [
    '#my-input-id',
    '.my-protected-class'
]});

// Password fields are no longer protected
var cobrowse = new coBrowseVisitor({
    passwords: true
});

To protect client-side input fields and other elements from transmitting actual data to the agent you can specify an array of HTML element selectors in the config initialization parameter.

Password fields are protected by default. To override this you can specify the boolean passwords property inside config

Protected elements don’t send any actual data to the agent. Instead they will see the visitor writing asterisks. The length of the data is not provided either: protected elements only transmit up to 5 characters.

Widgets

The configuration option widgets controls the behavior of the visitor pin dialog UI. It currently supports these properties:

Option Type Default Description
top string 50%  Fixed top position of the pin dialog launch button
lang string 'en' Visitor widgets language
// Init config sample to set launch button position
{
    ui: true,
    widgets: {
        top: "25%"
    }
}

// Setting language to finnish
{
    widgets: {
        lang: "fi"
    }
}

About pin dialog

The pin dialog UI is a separate component. If cobrowse visitor config has ui: true it will download the dialog JS loader and initialize it on the fly in the global scope. The object is then defined as a window property:

window.cobrowseDialog

All configuration of the pin dialog UI should be done during the initialization of the cobrowse visitor object.

Events API

The cobrowse instance relies heavily on Javascript’s custom events. The visitor pin dialog UI is a separate object from the cobrowse instance. Custom events are used to pass data between these objects.

To trigger an event in the global scope, you can use the cobrowse instance event() method:

cobrowse.event('myevent')

document.addEventListener('myevent', function(event){
    if (event.value == 'somevalue')
        // do something
});

To pass values along with the custom event, you apply a second parameter:

cobrowse.event('myevent', 'somevalue')

Then you can create a listener like in the example on the right.

Giosg Events

By default, the cobrowse visitor will listen to javascript events originating from Giosg apps framework. Event names are prefixed with CoBrowse::

Supported Giosg events

Initialize session via Giosg apps channel

CoBrowse::GiosgInit => value=<session UUID string>

CoBrowse Events

Here’s a list of custom events used by cobrowse internally. They are prefixed with coBrowse for now. Likely to be changed in future.

Event  Params(=default) Description
coBrowseUiInit restore=true  Initializes the pin dialog UI, optionally displaying the session restored message
coBrowseAgentInitAll session=null Initializes UI and sets up a session
coBrowseAgentStart session=null Sets up a session on already active UI
coBrowseDisconnect Destroys active cobrowse session