0% found this document useful (0 votes)

40 views

LA Android Developer Guide

Uploaded by

ShareFile Pro

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

40 views

LA Android Developer Guide

Uploaded by

ShareFile Pro

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 63

LA Android Developer Guide

YRP1-508, 3-4 Hikari-no-Oka Yokosuka-Shi, Kanagawa, 239-0847, Japan

tel.: + 81-(0) 46-821-3362 | cba-japan.com
This document contains confidential information that is proprietary to CBA. No part of its contents
may be used, disclosed or conveyed to any party, in any manner whatsoever, without prior
written permission from CBA.
© Copyright 2023 CBA.

All rights reserved.

Updated: 2022-06-22

Document version: 1.64/1

Contact Information

For technical support or other queries, contact CBA Support at:

[email protected]

For our worldwide corporate office address, see:

https://www.cba-japan.com (Japanese) https://www.cba-gbl.com (English)

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 2

Contents
Introduction
Integration with an Existing Application
Adding the SDK Libraries and Assets
AndroidManifest Entries
The Application Object
Implementing AssistApplication
Starting a Support Session
Ending the support session
The AssistConfigBuilder
Escalating an existing call to include co-browse
Building with ProGuard
During a Co-browsing Session
Receiving Notifications
AssistAgentCobrowseListener
AssistSharedDocumentAuth
AssistSharedDocumentReceivedListener
AssistAnnotationListener
AssistCobrowseListener
AssistCobrowseAuthListener
ConnectionStatusListener
AssistErrorListener
Allow and Disallow Co-browse for an Agent
Agent accepted into co-browse
Agent rejected from co-browse
Pausing and Resuming a Co-browse Session
Sharing Documents
Disabling document close buttons
Annotations
Notification of new annotations
Notification of annotations cleared
Annotation Context

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 3

Example: Placing the agent’s name at the end of the annotation
Form Filling
Using a custom Adapter with a Spinner
Excluding elements from a view
Co-browsing Visual Indicator
WebSocket Reconnection Control
Connection Configuration
Using the ConnectionStatusListener interface
Cookies
Permissions
Agent and Element Permissions
Parent and Child Permissions
Default Permission
Permissions in Web Views
Internationalization
Integrating with FCSDK
Voice and Video Volume Control
Using CBA Live Assist without Voice and Video
Informing the Agent of the Correlation ID
Including a Second Agent
Consumer Session Creation
Session Token Creation
System Dialog Boxes
Password Fields
HTML 5 Canvas Drawing is not Co-browsed to Agent
Media is Transmitted when the App is in the Background

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 4

Introduction
This guide describes the Fusion Live Assist solution from a developer integration and impact
point of view. We assume that the reader is familiar with Android, Java, and the Android SDK.

Fusion Live Assist provides voice and video calling from a consumer to an agent, along with
co-browsing, and document push by the agent, and remote control and annotation of the
consumer’s screen by the agent. See the CBA Live Assist Overview and Installation Guide
for details of what that means in practice.

For ease of integration and development, Fusion Live Assist uses the Fusion Client SDK for
voice and video support, while exposing a simple API for co-browsing. When developing using
the CBA Live Assist SDK, you use the Fusion Client SDK to set up the call, and the CBA Live
Assist SDK for co-browsing. You therefore need at least a basic understanding of the Fusion
Client SDK in order to develop using CBA Live Assist (see the FCSDK Developer Guide).

This Developer Guide gives information on integrating the Fusion Live Assist SDK into an
Android application, and how to use it to provide the co-browsing functions to a consumer.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 5

Integration with an Existing Application
You can integrate CBA Live Assist with an existing Android application. You need to create an
Android project in whatever way your development environment specifies, and put any existing
code into it. For simplicity, the examples in the text assume that the project was empty, but a
similar approach works if you want to add the CBA Live Assist SDK to an existing Android
application.

Adding the SDK Libraries and Assets

Once you have an Android project, with its standard directory structure, you need to add the
appropriate files from the CBA Live Assist Android SDK zip file. The zip file contains the
following components that developers must integrate into their application in order to use CBA
Live Assist:

Component Description

A folder containing assets needed by the SDK.

assets
Copy the contents of this folder into the matching assets directory of the
application.

The artifacts needed to integrate an application with CBA Live Assist.

libs
Copy the assist-android-sdk1.x.x.jar file, fusionclient-android-sdkx.x.x.jar
file, and armeabi-v7a folder into the application’s libs build directory.

A folder containing resources needed by the SDK for the user interface.

res
Copy the contents of this folder into the matching res directory of the
application build directory.

AndroidManifest Entries

The CBA Live Assist SDK requires entries within the application’s AndroidManifest.xml. You
need to add these if they are not there already:

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 6

Under the root <manifest> element, add the following lines to enable the corresponding
features:

<uses-feature android:name=”android.feature.CAMERA”

android:required=”true” android:glEsVersion=”0x00020000”/>

<uses-feature android:name=”android.hardware.camera.autofocus”/>

Again under the root <manifest> element, add the following entries to enable these
permissions:

<uses-permission android:name=”android.permission.INTERNET”/>

<uses-permission android:name=”android.permission.RECORD_AUDIO”/>

<uses-permission android:name=”android.permission.CAMERA”/>

<uses-permission android:name=”android.permission.WRITE_EXTERNAL_STORAGE”/>

<uses-permission android:name=”android.permission.MODIFY_AUDIO_SETTINGS”/>

<uses-permission android:name=”android.permission.ACCESS_NETWORK_STATE”/>

<uses-permission android:name=”android.permission.WAKE_LOCK”/>

<uses-permission android:name=”android.permission.SYSTEM_ALERT_WINDOW”/>

Under the <application> element, add the following service entry:

You may want to add, under the <application> element, the following meta-data entries:

<meta-data android:name=”assist-host” android:value=””/>

<meta-data android:name=”assist-port” android:value=”8080”/>

<meta-data android:name=”assist-secure” android:value=”false”/>

These entries act as defaults for values which CBA Live Assist needs to be present, but which
you normally set using the application’s shared preferences, or by providing a serverHost value
to the configuration object when starting a CBA Live Assist session (see the The
AssistConfigBuilder section).

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 7

The Application Object

In order to take advantage of CBA Live Assist functions, subclass the AssistApplicationImpl
object, and make that class the main application class of your application:

package com.example;
import com.alicecallsbob.assist.sdk.core;

public class SampleAssistApplication extends AssistApplicationImpl

{

And in the AndroidManifest.xml:

Implementing AssistApplication

If you are integrating CBA Live Assist with an existing application, you may have an existing
application class which extends an Application class from another library. In this case you will not
be able to extend AssistApplicationImpl. In these circumstances, you should make your existing
application class implement the AssistApplication interface. To follow this pattern, the application
should construct and terminate an AssistCoreImpl object within the lifecycle of your application:

import android.app.Application;
import com.alicecallsbob.assist.sdk.core.AssistApplication;
import com.alicecallsbob.assist.sdk.core.AssistCore;
import com.alicecallsbob.assist.sdk.core.AssistCoreImpl;

public class SampleAssistApplication

extends Application implements AssistApplication
{
private AssistCore assistCore;

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 8

@Override
public void onCreate()
{
super.onCreate();
assistCore = new AssistCoreImpl(this);
}

@Override
public void onTerminate()
{
assistCore.terminate();
assistCore = null;
}

@Override
public AssistCore getAssistCore()
{
return assistCore;
}
}

Starting a Support Session

The application typically starts a CBA Live Assist support session in one of its Activity classes;
often, though not necessarily, its main Activity. This may be in response to user interaction (user
presses a Help button), or automatically by the program in certain circumstances (the user has
entered syntactically incorrect data into a form field, for instance). You do this using the
Assist.startSupport static call.

When you call startSupport, you provide an AssistConfig configuration item, the Application
object for the current application, and an AssistListener object which receives notification when
the support session ends.

The AssistListener interface contains a single non-deprecated method, onSupportEnded, which

offers an opportunity for the application to tidy up its user interface and generally do whatever
housekeeping it requires.

It also contains a deprecated method, onSupportError - we recommend that this should be given
no more than a skeleton implementation; to receive notifications of support errors, implement an
AssistErrorListener, and include it in the AssistConfig object (see the AssistErrorListener
section).

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 9

Note: An AssistListener implementation must be supplied, even if there is nothing for
onSupportEnded to do.

The application’s Application object must implement AssistApplication or extend

AssistApplicationImpl (see the The Application Object section). If it does not, startSupport throws
an Exception.

The AssistConfig object supplies the configuration for the CBA Live Assist session. The
recommended way to construct it is to use the AssistConfigBuilder class (see the The
AssistConfigBuilder section).

private class AssistListenerImpl implements AssistListener

{
void onSupportEnded(boolean endInitiatedLocally)
{
if (!endInitiatedLocally)
{
// Display "Agent ended session"
}
}

void onSupportError(AssistError errorType, String message)

{
}
}

AssistConfig config = new AssistConfigBuilder(getApplicationContext()).

setAgentName(“agent1”).
setServerHost(“127.0.0.1”).build();
Assist.startSupport(config, getApplication(), new AssistListenerImpl());

Ending the support session

The agent may end the support session, or the application may end the session by calling
Assist.endSupport. In both cases, the CBA Live Assist SDK removes the user interface
elements which it added, and calls the onSupportEnded notification; the application only needs
to restore changes which it itself has made.

The AssistConfigBuilder

The com.alicecallsbob.assist.sdk.config.impl.AssistConfigBuilder supports the following

properties:

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 10

Default
Method Value or Description
Behavior

Value of the
Base URL of CBA Live Assist server and
assist-host
FCSDK Gateway, including only the
key in the
hostname, or IP address. If not set using
setServerHost application’s
setServerHost, this value must be set in the
shared
application’s shared preferences or
preferences
metadata for CBA Live Assist to work.
or meta data.

User name of agent or agent group, if that

agent or agent group is local to the Web
setAgentName agent1
Gateway; otherwise, the full SIP URI of an
agent or queue.

Whether to connect using HTTPS (rather

setConnectSecurely false
than HTTP) to the supplied server host

Set whether to show video, and from which

parties. The AssistMediaMode class
provides the enumeration to control this
parameter.

voice and Values include the following:

setMediaMode video to and
from agent ●voice/video in both directions

●voice in both directions, but video from the

agent only

●voice only.

setCorrelationId generated ID of the co-browsing session.

Name to identify the consumer in event logs

(see the CBA Live Assist Overview and
setAuditName empty string Installation Guide for more details on
event logging). This string should be URL
encoded.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 11

Port for the http(s) connection to CBA Live
setServerPort 8080
Assist server.

setSessionToken Web Gateway session token (if required).

A HostnameVerifier object to validate

connections made by the SDK to secure
setHostnameVerifier
URLs (including pushed content, such as
documents).

A TrustMananger object to validate

connections made by the SDK to secure
setTrustManager
URLs (including pushed content, such as
documents).

Shows an
Supply an AssistSharedDocumentAuth
AlertDialog
implementation that is notified when the
prompting
agent shares a document with the
the user to
setSharedDocument consumer. Allows the application to accept
choose
AuthHandler or reject a document.
whether to
accept or
See the AssistSharedDocumentAuth
reject a
section.
document

Supply an
AssistSharedDocumentReceivedListener
implementation that is notified about
successful and unsuccessful incoming
shared documents. Also handles document
setSharedDocument closure notifications, and provides an API
ReceivedListener for programmatically closing currently
opened documents.

See the
AssistSharedDocumentReceivedListener
section.

setSharedDocument All margins 0 An AssistSharedDocumentViewConstraints

ViewConstraints object with the desired left, top, right and

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 12

bottom margins within which shared
documents will be displayed or constrained.

An implementation of AssistErrorListener
used for listening to errors from the CBA
Live Assist SDK.
setErrorListener

See the AssistErrorListener section for error

codes.

Supply an AssistAnnotationListener
implementation that is notified when an
annotation is drawn on the consumer
application, and when annotations are
setAssistAnnotation
cleared. It also allows the client to receive
Listener
an AnnotationContext that they can use to
manually clear annotations.

See the AssistAnnotationListener section.

Shows an
AlertDialog Supply an AssistCobrowseAuthListener
prompting implementation that is notified when the
the user to agent requests co-browse with the
choose consumer. Allows the application to accept
setCobrowseAuthListener
whether to or reject the co-browse request.
accept or
reject the co See the AssistCobrowseAuthListener
browse section.
request

The value set is placed in the SIP User to

User header.

Note: The UUI can only be used when

setUUI Anonymous Consumer Access is set to
trusted mode. See the CBA Live Assist
Architecture Guide for further information.
The UUI is ignored if the session token is
provided.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 13

An implementation of the
AssistCobrowseListener that overrides the
default visual indicator when the application
setCobrowseListener screen is shared.

See the Co-browsing Visual Indicator

section.

An implementation of the
AssistAgentCobrowseListener which
receives notifications when an agent joins,
setAgentCobrowseListener leaves, or requests to join the session.

See the AssistAgentCobrowseListener

section.

An implementation of the
ConnectionStatusListener which will receive
setConnectionStatus notifications about the state of the
Listener connection to the CBA Live Assist server.

See the ConnectionStatusListener section.

A ConnectionProfile object, containing retry

intervals and timeouts for establishing and
maintaining the connection to the CBA Live
setConnectionProfile
Assist server.

See the Connection Configuration section.

Escalating an existing call to include co-browse

In most cases, the application calls startSupport with an agent name, and allows CBA Live
Assist to set up a call to the agent and implicitly add CBA Live Assist support to that call.
However, there may be cases where a call to an agent already exists, and the application needs
to add CBA Live Assist support capabilities. To do this, you need to supply the session token
and a correlation ID in the AssistConfig which you supply to startSupport; and the agent needs
to connect to the same session. The CBA Live Assist server provides some support for doing
this:

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 14

1. The application connects to a specific URL on the CBA Live Assist server, to request a
short code (error handling omitted):

JsonObjectRequest request = new JsonObjectRequest(Request.Method.PUT,

assistServerAddr + "/assistserver/shortcode/create",
null, new ShortCodeResponseListener(), new ErrorListener());
queue.add(request);

The Volley RequestQueue object should already exist.

2. The application uses the short code in another call to a URL on the CBA Live Assist server,
and receives a JSON object containing a session token and a correlation ID:

class ShortCodeResponseListener extends Response.Listener<JSONObject>

{
public void onResponse(JSONObject response)
{
String shortCode = response.getString("sortCode");
JsonObjectRequest request = new JsonObjectRequest(Request.Method.GET,
assistServerAddr + "/assistserver/shortcode/consumer?appkey=" + shortCode,
null, new SessionResponseListener(), new ErrorListener());
queue.add(request);
}
}

3. The application passes those values to the AssistConfigBuilder, and passes the AssistConfig
object to startSupport:

class SessionResponseListener extends Response.Listener<JSONObject>

{
public void onResponse(JSONObject response)
{
String correlationId = response.getString("cid");
String sessionToken = response.getString("session-token");
builder.setCorrelationId(correlationId).
setSessionToken(sessionToken);

Assist.startSupport(builder.build, getApplication(),
new EndSupportListener());
}
}

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 15

More configuration can be set in the AssistConfigBuilder. In particular, you may want to set an
AssistCobrowseAuthListener in order to validate the agent when the session has started and
they request to co-browse.

4. The agent uses the same short code to get a JSON object containing the session token and
correlation ID, which it then uses to connect to the same CBA Live Assist support session
(see the CBA Live Assist Agent Console Developer Guide). Informing the agent of the
short code is a matter for the application. It could be something as simple as having it
displayed on the consumer’s screen and having the consumer read it to the agent on the
existing call (this is how the sample application does it).

Note:

The short code expires after 5 minutes, or when it has been used by both agent and
consumer to connect to the same session.

If you wish to define an audit name to identify the consumer in event logs (see the CBA Live
Assist Overview and Installation Guide for more details on event logging), include an
auditName parameter in the URL which creates the short code:

/assistserver/shortcode/create?auditName=consumer

Building with ProGuard

The CBA Live Assist SDK includes a file, proguard-project.txt, that can be used or merged with
an existing ProGuard configuration file for an application; copy the proguard-project.txt to the
root of the application project, alongside the project.properties file.

Typically, the project.properties of the application should specify both the local and parent
ProGuard configuration files. For example:

proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt

You can modify the proguard-project.txt configuration to add additional ProGuard rules as
necessary.

Note: If you are building with only co-browsing support (because your application does not
support voice and video calling; see the Using CBA Live Assist without Voice and Video section),
you should ignore the CSDK files which would otherwise be referenced in the build.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 16

During a Co-browsing Session
While a co-browsing session is active (after the application has called startSupport successfully,
and before either it calls endSupport or receives the onSupportEnded notification to indicate that
the agent has ended the support session), the application may:

Accept an agent into, or expel the agent from, the co-browsing session

Pause and resume the co-browsing session

Receive a document from the agent

Push a document to the agent

Receive an annotation (a piece of text or drawing to show on the device’s screen, overlaid
on the application’s view) from the agent

Have a form on its screen wholly or partly filled in by the agent

Actions which are initiated by the application (such as pushing a document to the agent) require
it to call one of the methods on the Assist object.

Actions initiated by the agent (such as annotating the consumer’s screen) can in general be
allowed to proceed without interference from the application, as the CBA Live Assist SDK
manages them, overlaying the user’s screen with its own user interface where necessary.
However, the application can receive notifications of these events by implementing of one of the
various Listener interfaces (see the Receiving Notifications section).

Receiving Notifications

You can receive notifications of events of interest on the various Listener interfaces which you
can set in the AssistConfig object which is passed to the Assist.startSupport method. In most
cases you can ignore these interfaces, but if you need to receive any of these notifications, you
need to implement the appropriate interface in some class, and pass an instance of that class in
the configuration (see the The AssistConfigBuilder section).

AssistAgentCobrowseListener

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 17

Implementing the com.alicecallsbob.assist.sdk.core.AssistAgentCobrowseListener interface
enables the application to receive the following notifications:

agentJoinedSession(agent)

This callback indicates that an agent has answered the support call and joined the support
session; this occurs before the agent either requests or initiates co-browsing. The callback
allows the developer to pre-approve the agent into the co-browse, before the agent makes the
request.

agentRequestedCobrowse(agent)

This callback notifies the application that the agent has specifically requested to co-browse.
There is no specific requirement for the application to allow or disallow co-browsing at this point,
but it is an obvious point to do so.

agentJoinedCobrowse(agent)

This callback occurs when the agent joins the co-browse session.

agentLeftCobrowse(agent)

This callback occurs when the agent leaves the co-browse session, and can no longer see the
consumer’s screen. Leaving the co-browse also resets the agent’s co-browse permission; the
agent may subsequently request co-browse access again.

agentLeftSession(agent)

This callback notifies the application that the agent has left the overall support session.

The default implementation displays a dialog box on the consumer’s device, asking whether to
allow co-browsing or not. If the consumer allows co-browsing, it allows any agent into the co-
browsing session whenever they request it. Implementing this interface can give the application
more control over which agents are allowed into the co-browsing session, and when.

AssistSharedDocumentAuth
The com.alicecallsbob.assist.sdk.config.impl.AssistSharedDocumentAuth interface gives the
application notification when an agent pushes a document or URI to the consumer. It has a
single method:

handleSharedDocumentAuth(AssistSharedDocumentAuthEvent)

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 18

The agent has pushed a document to the consumer. The
com.alicecallsbob.assist.sdk.config.impl.AssistSharedDocumentAuthEvent object has two
methods, acceptDocument, and rejectDocument. The implementation should call one of them.

By default, CBA Live Assist displays a dialog box, allowing the user to accept or reject the
document. You might implement this interface to automatically accept any document.

AssistSharedDocumentReceivedListener

The com.alicecallsbob.assist.sdk.config.impl.AssistSharedDocumentReceivedListener interface

allows the application to receive notifications when the agent pushes a document or URI to the
consumer. It contains three methods:

onDocumentReceived(AssistSharedDocument)

Indicates that the document has been received and displayed. The
com.alicecallsbob.assist.sdk.core.AssistSharedDocument object gives access to the document’s
ID, its metadata (extra information supplied by the agent in the form of a String), and a close
method.

onError(AssistSharedDocument)

Indicates that the SDK cannot display the document; by default, it displays a error overlay to
inform the user.

onDocumentClosed(AssistSharedDocumentClosedEvent)

Indicates that a document has been closed. You can retrieve the AssistSharedDocuement object,
and an indication of the source of the document, using methods on the
com.alicecallsbob.assist.sdk.core.AssistSharedDocumentClosedEvent.

By default, the CBA Live Assist SDK displays the document. Acceptable document types are:
PDF, and the image formats GIF, PNG, and JPG/JPEG.

AssistAnnotationListener
The com.alicecallsbob.assist.sdk.config.impl.AssistAnnotationListener allows the client
application to receive notifications relating to annotations sent by the agent:

newAnnotation(annotation, sourceName)

Notification that an annotation has been received from an agent.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 19

annotationsCleared()

Called when an agent clears the annotations.

annotationContextInitialised(AnnotationContext)

Receives the com.alicecallsbob.assist.sdk.core.AnnotationContext for a support session when it

is ready to be used.

annotationContextEnded(AnnotationContext)

Notification that the AnnotationContext is no longer valid and should not be used.

You can implement this interface in order to control of the display and clearing of annotations
which the application receives from the agent. See the Annotations section for details of how you
might use these notifications.

AssistCobrowseListener
The com.alicecallsbob.assist.sdk.config.impl.AssistCobrowseListener contains two notifications,
onCobrowseActive and onCobrowseInactive, which allow the application to receive notifications
when co-browsing starts and stops. You might implement this to customize the display of a
notification to the user. See the Co-browsing Visual Indicator section for details.

AssistCobrowseAuthListener

The com.alicecallsbob.assist.sdk.config.impl.AssistCobrowseAuthListener interface gives the

application notification when an agent has requested to co-browse the consumer’s screen. It has
a single method:

onCobrowseRequested(AssistCobrowseAuthEvent)

The agent has requested a co-browse with the consumer. The

com.alicecallsbob.assist.sdk.config.impl.AssistCobrowseAuthEvent object has two methods,
acceptCobrowse, and rejectCobrowse. The listener implementation should call one of them.

By default, CBA Live Assist displays a dialog box when an agent requests co-browsing,
allowing the user to accept or reject the co-browse. You might implement this interface to avoid
asking the user each time, and instead use the application’s shared preferences setting to
decide whether to accept or reject the co-browse.

ConnectionStatusListener

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 20

The com.alicecallsbob.assist.sdk.transportConnectionStatusListener has the following methods,
which supply notifications about the connection status of the WebSocket connection to the CBA
Live Assist server:

onConnect()

Received when the WebSocket becomes connected to the CBA Live Assist server, so that the
application can send and receive messages.

Note: The application does not need to wait to receive this notification before it can use the CBA
Live Assist API methods.

onDisconnect(reason, connector)

Received when the WebSocket connection to the CBA Live Assist server has been lost, or has
failed to reconnect. The reason is a
com.alicecallsbob.assist.sdk.transport.websocket.WebSocketException.

onTerminated(reason)

Received when the WebSocket connection with the CBA Live Assist server has terminated, and
there will be no more reconnection attempts. The reason is a WebSocketException.

willRetry(retryInSeconds, retryAttemptNumber, maximumRetryAttempts, connector)

retryInSeconds is a double, while retryAttemptNumber and maximumRetryAttempts are ints. The

notification indicates that the CBA Live Assist SDK is preparing to retry an automatic
reconnection attempt (controlled by the ConnectionProfile object which may be supplied in the
configuration passed to startSupport - see the Connection Configuration section).

There are two reasons for implementing your own ConnectionStatusListener:

to log the connection attempts and other messages to somewhere other than the default
Android log.

to implement your own reconnection strategy which is not covered by setting the
ConnectionProfile. See the Using the ConnectionStatusListener interface section for details
of how you might use an implementation of this interface.

AssistErrorListener

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 21

The com.alicecallsbob.assist.sdk.core.AssistErrorListener has a single notification method,
onSupportError(AssistErrorEvent), which the application receives when an error occurs. The
com.alicecallsbob.assist.sdk.core.ErrorEvent has a single method, getError, which returns one of
the possible AssistErrorListener.AssistError error codes:

Code Meaning

Error in the call. This may be due to no media, a

CALL_ERROR
network failure, or some other reason

CALL_SESSION_NOT_STARTED Attempt to co-browse before the session has started

Unable to even try to dial (for example, the number to

CALL_DIAL_FAILED
dial might be invalid)

CALL_CREATION_FAILED Unable to create a Call object

The dial operation failed because the callee did not

CALL_TIMEOUT
answer the call inside the network’s timeout

Tried to share a document when co-browsing is not

active.
CALL_FAILED
Tried to allow or disallow co-browsing for an agent
when support is not active

The dialed number is formally valid, but could not be

CALLEE_NOT_FOUND found. It might not be in use, or not accessible on the
network.

SESSION_IN_PROGRESS There is already a session in use

SESSION_CREATION_FAILURE Error connecting to CBA Live Assist server

Allow and Disallow Co-browse for an Agent

You may wish to remove a specific agent from the co-browsing session. To do this, call:

Assist.disallowCobrowseForAgent(agent);

passing in the Agent object received in one of the notifications on the

AssistAgentCobrowseListener interface (see the AssistAgentCobrowseListener section).

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 22

If the agent is already in the co-browse session, they are removed from it; if they are not in the
co-browse session, they will not be admitted until the application calls:

Assist.allowCobrowseForAgent(agent);

When the application calls allowCobrowseForAgent, the specified agent joins the co-browse
session immediately.

Agent accepted into co-browse

When an agent is accepted into the co-browse, the following occurs:

1. Consumer starts support session.

2. Agent joins session.

3. agentJoinedSession callback fired in the consumer application.

4. Agent requests co-browse.

5. agentRequestedCobrowse callback fired in the consumer application.

6. The consumer application has logic that decides the agent is allowed access to the co-
browse. This logic could be based on permissions.

7. Agent is accepted into the co-browse.

8. Agent joins the co-browse.

9. agentJoinedCobrowse callback fired in the consumer application.

10. Agent can see the consumer’s screen.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 23

Agent rejected from co-browse
1. Agent requests co-browse.

2. agentRequestedCobrowse callback fired in the consumer application, with the agent’s

permissions.

3. Consumer application checks the agent permissions, and finds they do not have the
required permissions to view the current part of the application.

4. Consumer application rejects the agent’s request to join the co-browse, and the agent is
unable to see the consumer’s screen.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 24

Pausing and Resuming a Co-browse Session

The application can temporarily pause a co-browse session with the agent by calling:

Assist.pauseCobrowse();

While paused, the connection to the CBA Live Assist server remains open, but the co-browse
session is disabled, disabling annotations, document sharing, and so on as a consequence.
When the application wishes to resume the co-browsing session, it should call:

Assist.resumeCobrowse();

When the application pauses a co-browse, CBA Live Assist notifies the Agent Console, which
can present a notification or message to the agent to indicate what has happened.

Sharing Documents

As well as receiving shared documents from the agent (see the

AssistSharedDocumentReceivedListener section), applications can use the CBA Live Assist
SDK to share documents with the agent during a co-browsing session. Acceptable documents
are PDFs and images.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 25

Documents shared in this way are represented visually in the same way as documents that are
pushed from the agent: PDFs are full screen, and images are in windows that can be dragged,
re-sized, or moved.

Note: Sharing a document does not actually send the document to the agent, but simply displays
the document on the local device, so that both the consumer and the agent can see and co-
browse the document.

There are two methods exposed by the AssistDocumentShareManager object to handle

document sharing:

void shareDocumentUrl(URL, contentType, listener)

This method allows sharing a document given its URL. Typically, this would be used to share a
document on another machine.

void shareDocument(stream, contentType, listener)

This method allows sharing an InputStream containing the document’s data. Typically, this would
be used to share a document on the local machine.

To obtain the AssistDocumentShareManager, call Assist.getDocumentShareManager.

In each method, the application must supply the content type of the document. This is typically
application/pdf in the case of PDFs, or something like image/jpeg in the case of images (or
similar, for example image/png).

The application can also provide a AssistSharedDocumentListener implementation to receive

feedback on the state of the document; this argument can be null if not required. The listener
provides the following callbacks, similar to that of the
AssistAgentSharedDocumentReceivedListener API:

onOpened(AssistSharedDocument)

Called when the document is successfully opened, passing in a document object.

onError(AssistSharedDocument)

Called when an error overlay is displayed by CBA Live Assist due to the failure to successfully
display the shared document for some reason.

onDocumentClosed(AssistSharedDocumentClosedEvent)

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 26

Called when the document is closed (the event object provides information about the source of
the event, such as CONSUMER, AGENT, or END_SUPPORT to indicate where the source of the
close originated from).

Note: The AssistSharedDocumentReceivedListener and the AssistSharedDocumentListener

interfaces share a superclass, and therefore have some method signatures in common. This
means that all documents represented by an AssistSharedDocument, whether pushed by the
agent to the consumer or pushed by the consumer to the agent, have a getId method. IDs only
exist for documents pushed by the agent and received by the
AssistSharedDocumentReceivedListener interface; all IDs returned by getId on
AssistSharedDocument objects received in the AssistSharedDocumentListener interface are -1.

If the application calls either of these methods while the consumer is not in a co-browse session,
they throw an AssistNotInCobrowseException. You cannot share a document with an agent if you
are not actually co-browsing.

If the application provides an invalid content type (that is, it is not a PDF or image), both methods
throw an AssistInvalidContentTypeException.

Note: This is simply a check on the contentType argument provided to the API; if the call
provides a valid content type but invalid data (for example, trying to load a .DOCX file, but
specifying the content type as a PDF) then the methods do not throw this exception; instead,
CBA Live Assist displays an error overlay and fires the onError method.

The major distinction between errors that are presented by throwing an Exception or the onError
callback on the listener, is that the Exceptions handle anything that can be synchronously
verified as incorrect (such as not being in a co-browse); onError is for errors that occur during the
asynchronous loading of the document (for example, if the call provides a valid argument, such
as a well-formed URL, but the URL returns a 404 Not found error message, then CBA Live
Assist can not report that synchronously).

Example:

class DocListener extends AssistSharedDocumentListener

{
@Override
public void onOpened(AssistSharedDocument document)
{
}
@Override
public void onError(AssistSharedDocument document)
{

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 27

Toast.makeText(this, "Error opening document", Toat.LENGTH_SHORT).show();
}
@Override
public void onDocumentClosed(AssistSharedDocumentClosedEvent event)
{
if (event.getSource() == AssistSharedDocumentClosedSource.AGENT)
{
Toast.makeText(this, "Agent closed the document",
Toast.LENGTH_SHORT).show();
}
}
}

try
{
AssistDocumentShareManager sm = Assist.getDocumentShareManager();
FileInputStream fis = new FileInputStream("document.pdf");
sm.shareDocument(fis, "application/pdf", new DocListener());
}
catch (AssistNotInCobrowseException e)
{
Toast.makeText(this,
"Error: can't share document when not in cobrowse",
Toast.LENGTH_SHORT).show();
}
catch (AssistInvalidContentTypeException e)
{
Toast.makeText(this,
"Error: document must be an image or pdf", Toast.LENGTH_SHORT).show();
}

Disabling document close buttons

To disable the close buttons in shared document views in the CBA Live Assist SDK, edit the
following files in the layout resource directory accompanying the SDK, to remove the View UI
component which has the assist_doc_close ID:

assist_closeable_document.xml

assist_closeable_popup.xml

assist_closeable_single_page_document.xml

assist_error_popup.xml

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 28

For instance, in the assist_closable_document.xml, remove or comment out the Button element
which has the assist_doc_close ID:

<com.alicecallsbob.assist.sdk.overlay.view.impl.AssistRelativeLayout

xmlns:android=”http://schemas.android.com/apk/res/android"

android:layout_width=”match_parent”

android:layout_height=”match_parent”

android:background=”@color/document_popup_background”>

<FrameLayout

android:id=”@+id/assist_popup_content”

android:layout_width=”match_parent”

android:layout_height=”match_parent”/>

<!–

<Button

android:id=”@+id/assist_doc_close”

android:layout_width=”wrap_content”

android:layout_height=”wrap_content”

android:text=”@string/close_popup_text”

android:textColor=”#FFFFFF”

android:layout_alignTop=”@id/assist_popup_content”

android:layout_alignRight=”@id/assist_popup_content”/>

-->

</com.alicecallsbob.assist.sdk.overlay.view.impl.AssistRelativeLayout>

and similarly for the other files.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 29

Annotations

By default, the CBA Live Assist SDK displays any annotations which the application receives
on an overlay, so that the consumer can see them together with their own screen. Normally an
application needs to do nothing further, but if it needs to receive notifications when an annotation
arrives, it can implement the AssistAnnotationListener interface, and supply the implementation
in the AssistConfig object (see the The AssistConfigBuilder section).

The AssistAnnotationListener offers:

Notification of new annotations received

Notification of annotations cleared

An AnnotationContext for each support session, which can be used to manually clear
annotations, or to turn automatic clearing on or off.

Notification of new annotations

Implement the following method on the AssistAnnotationListener:

@Override
public void newAnnotation(Annotation annotation, String sourceName)
{
}

The received Annotation object contains the following methods:

Path getPath()

This is the standard Android library Path object that is used to draw the new Annotation

int getStrokeColour()

int getStrokeWidth()

float getStrokeOpacity()

The sourceName is the name of the source that created the annotation, for example the agent’s
name.

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 30

Notification of annotations cleared

Implement the following method on the AssistAnnotationListener:

@Override
public void annotationsCleared()
{

This method is called every time the annotations are cleared on the screen, regardless of how it
is triggered. For example, the method is called if the agent clears annotations, or if the
application calls the AnnotationContext.clearAnnotations method (see the Annotation Context
section).

Annotation Context

You receive an AnnotationContext in the annotationContextInitialised and

annotationContextEnded methods. You can use the AnnotationContext to take control of clearing
annotations manually. CBA Live Assist creates a new context for each support session, lasting
as long as the support session does. The AnnotationContext throws an IllegalStateException if
the application calls any of its methods after it receives the annotationContextEnded callback.

The application can turn automatic clearing of annotations off or on by calling the
setClearAnnotationsOnScreenChange method, passing false to turn them off and true to turn
them on. Automatic clearing can be set at any time during the support session. Typically,
applications set it to false to enable other views to draw over the support screen without clearing
the annotations:

private AnnotationContext annotationContext;

@Override
public void annotationContextInitialised(AnnotationContext annotationContext)
{
// turn off automatic annotation clearing
annotationContext.setClearAnnotationsOnScreenChange(false);
// store AnnotationContext to be able to clear annotations later
this.annotationContext = annotationContext;
}

@Override

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 31

public void annotationContextEnded(AnnotationContext annotationContext)
{
// discard the annotationContext at this point
if (annotationContext.equals(this.annotationContext))
{
this.annotationContext = null;
}
}

public void clearAnnotations()

{
if (annotationContext \!= null)
{
annotationContext.clearAnnotations();
}
}

Example: Placing the agent’s name at the end of the annotation

This example describes how to display a label at the end of an annotation, showing the name of
the agent who made it.

Implement the annotationContextInitialised method to disable automatic clearing of

annotations, and annotationsCleared and annotationContextEnded to do nothing.

Implement newAnnotation to get the path information from the annotation:

public void newAnnotation(Annotation annotation, String sourceName)

{
Path path = annotation.getPath();
}

You can obtain the Path using getPath; you can then get the end point and tangent of the
annotation from the Path object. You can use the end point and tangent to place a label at
the end of the line and facing in the direction of the annotation.

Use the standard Android library class PathMeasure to obtain the end point and tangent of
the annotation Path:

final PathMeasure pm = new PathMeasure(path, false);

final float length = pm.getLength();

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 32

final float[] endPoint = new float[2];

final float[] tangent = new float[2];

pm.getPosTan(length, endPoint, tangent);

The call to getPosTan causes the endPoint[] and tangent[] to be populated with the end point X
and Y co-ordinates and tangent of the Path at the end of the annotation:

private Bitmap annotationBitmap;

@Override
public void annotationContextInitialised(AnnotationContext annotationContext)
{
annotationContext.setClearAnnotationsOnScreenChange(false);
}

@Override
public void annotationContextEnded(AnnotationContext annotationContext)
{
}

@Override
public void annotationsCleared()
{
}

@Override
public void newAnnotation(Annotation annotation, String sourceName)
{
Path path = annotation.getPath();
PathMeasure pm = new PathMeasure(path, false);
float length = pm.getLength();
float[] endPoint = new float[2];
float[] tangent = new float[2];
pm.getPosTan(length, endPoint, tangent);

Paint paint = new Paint();

paint.setColor(annotation.getStrokeColour());
paint.setStrokeWidth(annotation.getStrokeWidth());
paint.setStrokeOpacity(annotation.getStrokeOpacity());

annotationBitmap = Bitmap.createBitmap(100, 100, Bitmap.Config.ARGB_8888);

Canvas canvas = new Canvas(annotationBitmap);
canvas.drawPath(path, paint);

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 33

canvas.drawPosText(sourceName, endPoint, paint);
}

The annotationBitmap now has the annotation and the agent’s name, and is available for use
outside the listener (if a getter is provided). The strokeColour, strokeWidth, and strokeOpacity
found on the Annotation object are used to keep the label consistent with the annotation.

Form Filling

One of the main reasons for a consumer to ask for help, or for an agent to request a co-browse,
is to enable the agent to help the consumer to complete a form which is displayed on their
device. The agent can do this whenever a CBA Live Assist co-browse session is active, without
further intervention from the application, but there are some constraints on how forms should be
designed.

The CBA Live Assist SDK automatically detects form fields represented by EditText,
RadioButton, CheckBox, or Spinner View types, and relays these forms to the agent so that the
agent can fill in values for the user. You must provide these form fields with unique labels in the
layout.xml, in one of the following ways:

setting the android:contentDescription attribute inside the xml element which defines the
field itself:

<EditText

android:layout_width=”wrap_content”

android:layout_height=”wrap_content”

android:inputType=”number”

android:ems=”10”

android:contentDescription=”Other Loans”

providing a label for the field and including the android:labelFor attribute inside the label’s
xml element:

<TextView

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 34

android:layout_width=”wrap_content”

android:layout_height=”wrap_content”

android:text=”Other Loans: “

android:layout_gravity=”center_vertical”

android:labelFor=”@+id/field”

For View instances where the inputType attribute may be specified, the SDK automatically
prevents the agent from performing form fill on any password-related inputType. These include
textPassword, textWebPassword, textVisiblePassword, and numberPassword inputTypes. In
order to successfully exclude these fields, CBA Live Assist SDK expects them to be the only
inputType present on the given View.

Note: While the SDK prevents these fields from being presented to the agent as fillable form
data, it does not prevent them from being visible as part of the co-browse. You can hide them by
adding the appropriate tag or permission to the View (see the Excluding elements from a view
section).

Using a custom Adapter with a Spinner

If you use a custom Adapter to provide the data for a Spinner, you must implement the
Adapter.getItem(position) method to return some object. The Spinner does not display in the
agent’s form editor if getItem(position) simply returns null.

Most applications implement getItem(position) to return a String; if it returns an object other than
a string, you should override that object’s toString method to return the string value that you want
to be displayed on the device. This ensures that the agent sees the correct values for the spinner
in the form editor; if you do not override toString, the agent will see the object ID for each spinner
item, rather than the value that is displayed on the device.

Excluding elements from a view

When an agent is co-browsing a form, you may not want the agent to see every control on the
form. Some may be irrelevant, and some may be private to the consumer.

You can hide an element by assigning a special tag to it. To exclude an area of the screen from
the screenshare, add this tag to the View object representing the area:

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 35

view.setTag(Assist.PRIVATE_VIEW_TAG, true);

For more detailed control over element visibility, see the Permissions section.

Note: If you are using a WebView, and using HTML elements on that WebView, you cannot
exclude individual HTML elements from being seen by the agent. You can exclude the whole
WebView using the above techniques, but the methods described in the CBA Live Assist Web
Developer Guide for masking individual elements do not work. See the Permissions in Web
Views section for a technique which does.

Co-browsing Visual Indicator

The SDK provides a means to customize the visual indication displayed during screen sharing.
The default implementation displays a notification icon in the notification bar during the
application screenshare, and a toast when the sharing begins and ends. To use your own icon,
place it in the res/drawable folder, and name it launcher_icon.png.

If you want to change this behavior, and not simply use your own icon, provide an
implementation of the AssistCobrowseListener to the AssistConfigBuilder:

public class CobrowsingListener implements AssistCobrowseListener

{
@Override
public void onCobrowseActive()
{
..implementation code
}
@Override
public void onCobrowseInactive()
{
..implementation code
}
}

See the the AssistCobrowseListener section for details.

WebSocket Reconnection Control

When a co-browse session disconnects due to technical issues, the default behavior is to
attempt to reconnect six times at increasing intervals. You can control this behavior by passing in

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 36

one or both of the following when the application calls startSupport (see the The
AssistConfigBuilder section):

Connection configuration

An implementation of ConnectionStatusListener used to listen for connection events,

allowing an application to perform its own reconnection handling, or to inform the user of the
status of the current connection.

Connection Configuration

You can set the connection configuration by specifying a ConnectionProfile in the AssistConfig
object which you pass in when the application calls startSupport. You can use a builder for the
ConnectionProfile, just as you can for the AssistConfig itself:

ConnectionProfile profile = new ConnectionProfile.Builder().

setInitialConnectionTimeout(30.0).

setRetryIntervals(5.0, 10.0, 15.0, 20.0).

setReconnectTimeouts(0.1, 1.0, 10.0).build();

AssistConfig config = new AssistConfigBuilder(getApplicationContext()).

setConnectionProfile(profile).build();

Assist.startSupport(config, …);

The above example sets a timeout for the initial connection of 30 seconds; if the connection is
lost, it will try to reconnect 3 times, at intervals of 5, 10, and 15 seconds. The first reconnection
attempt will time out after 0.1 seconds, the second after 1 second, and the third after 10
seconds.

The ConnectionProfile settings have default values, so there is no need to specify all (or any) of
them. Default values and behavior is as follows:

Item Default Description

initialConnectionTimeout 30.0 A Double value which defines the maximum time

in seconds the initial WebSocket connection

© 2023 CBA | All Rights Reserved | Unauthorized use prohibited. Page 37

attempt tries to connect.

An array of Double values which defines the

[1.0, 2.0, number of automatic reconnection attempts, and
retryIntervals 4.0, 8.0, the time in seconds between each attempt. If
16.0,32.0] you specify an empty array, CBA Live Assist
does not try to reconnect automatically.

An array of Double values which define the

maximum time in seconds for each WebSocket
reconnection to try to reconnect before failing.
The array of values corresponds to the values in
retryIntervals - as each value in retryIntervals is
reconnectTimeouts [5.0] used, the corresponding value is used from this
array. If the length of the retryIntervals is greater
than that of reconnectionTimeouts, then CBA
Live Assist uses the last value of the
reconnectionTimeouts array for all remaining
reconnection attempts.

Note: Reconnection applies only to the case where CBA Live Assist loses an existing
connection; if the initial connection attempt fails, CBA Live Assist does not retry automatically.

Using the ConnectionStatusListener interface

If the default reconnection behavior of CBA Live Assist is not what you want, even after
changing the configuration, you can implement the ConnectionStatusListener interface to
implement your own reconnection logic, and include it in the AssistConfig object which you pass
to startSupport - see the Starting a Support Session section and the ConnectionStatusListener
section for details. Note:

If you do not specify a ConnectionProfile in the AssistConfig, CBA Live Assist will use its
default reconnection behavior.

If you specify retryIntervals and reconnectionTimeouts in the ConnectionProfile, CBA Live

Assist will use its default reconnection behavior, but using those values instead of the
defaults for the number and timing of reconnection attempts.

You can turn off the default reconnection behavior, and take full control of reconnection, by
specifying an empty list for retryIntervals.

When implementing your own reconnection logic, the most important notifications you receive
are onDisconnect (called whenever the connection is lost) and willRetry (called when automatic
reconnection is occurring, and there are more reconnection attempts to come). Both these
methods include a Connector object in their arguments; you can use the Connector object to
make a reconnection attempt, or to terminate all reconnection attempts.

Method Description

Called for the initial WebSocket failure, and for every failed reconnection
attempt (including the last one).

This method is called regardless of whether retryIntervals is specified (that

is, whether automatic reconnection is active or not).

onDisconnect The connector object allows the implementing class to control

reconnection, even if reconnection is automatic. For example, an
application might decide to give up reconnection attempts even if more
reconnection attempts would normally occur; or to try the next
reconnection attempt immediately without waiting until the next retry
interval has passed.

Called under the following conditions:

when the WebSocket connection is lost; or

when a reconnection attempt fails and automatic reconnections are

occurring (retryIntervals is a non-empty array) and there are more
willRetry automatic reconnection attempts to be made.

This method is called after the onDisconnect method.

Use the Connector to override reconnection behavior. For example, to

make a reconnect attempt immediately.

Called when a reconnection attempt succeeds.

This may be useful to clear an error indication in the application UI, or for
onConnect
canceling reconnection attempts if the application is managing its own
reconnections.

Called under the following conditions:

when all reconnection attempts have been made (and failed); or

onTerminated
when either the Connector.disconnect method or Assist.endSupport
method is called.

Example - make a reconnection attempt immediately on disconnection:

In this example, the default reconnection behavior has been disabled, and the application
reconnection behavior is dependent on the reason for disconnection.

void onDisconnect(WebSocketException reason, Connector connector)

{
switch(reason.getCode())
{
case ERR\_ONE:
// Try to reconnect with a timeout of 2 seconds
connector.reconnect(2.0);
break;
case ERR\_TWO:
// Terminate connection
connector.terminate(new Exception("Cannot reconnect"));
break;
default:
// Try to reconnect with a timeout of 5 seconds
connector.reconnect(5.0);
break;
}
}

Example - terminate reconnection attempts in response to user command:

In this example, the default reconnection behavior has not been disabled, but there is a UI
control which the user can press to short-circuit the reconnection attempts. If the user has not
terminated the connection attempts, automatic reconnection attempts continue.

void willRetry(double retryInSeconds, int retryAttemptNumber, int

maximumRetryAttempts, Connector connector)
{
if (userHasTerminatedConnection)
{

connector.terminate(new Exception("User has terminated connection"));
}
}

Cookies
The CBA Live Assist SDK uses the following separate cookie handling and storage
mechanisms:

For any HTTP or HTTPS connections originating from WebView objects controlled by CBA
Live Assist, the SDK uses any cookies set using the global WebView CookieManager. You
can access the global CookieManager using:

android.webkit.CookieManager.getInstance();

For HTTP or HTTPS connections originating from the SDK outside a WebView, the SDK
uses cookies set using the default system java.net.CookieHandler object. You can access
this using:

java.net.CookieHandler.getDefault();

You can set a new default CookieHandler using:

java.net.CookieHandler.setDefault(bespokeCookieHandler);

CBA Live Assist does not set any cookies itself.

Note: CBA Live Assist does not supply a default CookieHandler - this is the responsibility of the
application.

Permissions
You can use permissions to prevent an agent from interacting with, or even seeing, a UI control.
Whether an agent can see a particular control or not depends upon both the agent’s and the
control element’s permissions.

Control element permissions

Client applications assign permission markers to UI control elements by calling the

Assist.setPermissionForView method:

Assist.setPermissionForView(“X”, control);

where X is the permission marker to be set on the control.

Each UI element has at most one permission marker value; elements which do not have a
permission marker inherit their parent element’s permission marker; an element which does not
have a permission marker either assigned explicitly or inherited from its parent, is assigned the
default permission marker.

The default permission is explained further in the Default Permission section.

Agent permissions

Agents have two sets of permissions, viewable permissions and interactive permissions.
Each set may contain an arbitrary number of values. Agents which are not assigned any
permissions have the default permission for both interactive and viewable permission sets.

CBA Live Assist grants permissions to the agent when the agent presents a Session Token
Description to the CBA Live Assist server (see the CBA Live Assist Agent Console
Developer Guide for more information about setting agent permissions, and under what
circumstances the agent can be implicitly assigned the default permission).

The application can determine an agent’s permissions from the Agent object which it receives in
the methods of the AssistAgentCobrowseListener interface (see the
AssistAgentCobrowseListener section). If the application needs to examine this (for instance, to
notify the consumer that a particular control will not be visible to the agent), use the
Agent.getViewablePermissions and Agent.getInteractivePermissions methods.

Set<String> viewable = agent.getViewablePermissions();

Note: If the agent specifies permissions in the Session Token Description, but leaves both
the viewable set and interactive set empty, the agent will end up with no permissions, not even
the default permission.

The combination of the element’s and the agent’s permissions determines the visibility of a UI
element to an agent. A UI element is visible to a specific agent if, and only if, the agent’s set of
viewable permissions contains the permission marker assigned to or inherited by that element.
Similarly, an agent may interact with a UI element if and only if the agent’s set of interactive
permissions contains the element’s permission marker.

Permissions and permission markers are free-form text, which (apart from the reserved default
permission) are in the control of the application developer. CBA Live Assist will show to the
agent those, and only those, elements which the agent has permission to view; but it is up to the
application developer to ensure that each agent has the permissions they need, and that the UI
elements have corresponding permission markers assigned.

CBA Live Assist assumption: When an agent wishes to establish a co-browse, the permissions
the agent should have, as defined by the organization’s infrastructure, are known, and can be
translated into an equivalent set of permissions in the Session Description.

Agent and Element Permissions

Permissions are compound such that:

Agent Agent
Permission
viewable interactive
marker on Result
permission permission
element
set set

Agent can view and interact with

X [“X”] [“X”]
an element marked with X.

Agent can view the element

X [“X”] [] marked with X but cannot interact
with it.

X [] [“X”] Agent can neither view nor interact

with the element, because it does
not have X in its viewable set. (In
order to interact with an element,

and agent must first be able to
view it.)

Element marked with X is masked

or redacted, as Agent does not
X [] []
have the X permission in its
viewable or interactive set.

Element marked with X is masked

or redacted, because Agent does
X [“default”] [“default”]
not have the X permission in its
viewable or interactive set.

Agent can neither view nor interact

X [“default”] [“X”] with the element, because it does
not have X in its viewable set.

Agent can view the element,

because it has the X permission in
its viewable set; it cannot interact
X [“X”] [“default”]
with it, because it does not have
the X permission in its interactive
set.

Element marked with B is masked

or redacted, because Agent has X
B [“X”] [“X”]
permission and not B in their
permission set.

Agent can view and interact with

the element because they have the
default permission in their viewable
[“X”,“default”] [“X”,“default”]
and interactive sets, and the
element implicitly has the default
permission.

Element is masked or redacted,

[“X”] [“X”] because Agent’s sets do not
contain the default permission

[“default”] [“default”] Agent can view and interact with

the element, because they have

the default permission set for their
viewable and interactive set.

Element is masked or redacted,

[] [] because Agent’s sets do not
contains default permission

Agent can see the element

because they have the default
permission in their viewable set.
[“default”] [“X”] They cannot interact with it
because they do not have the
default permission in their
interactive set.

Element is masked or redacted

because the agent’s viewable set
does not contain B. The agent may
B [“X”] [“B”] not interact with an element which
they cannot see, even though they
have the appropriate permission in
their interactive permission set.

Element is viewable, because the

agent’s viewable set contains B;
B [“B”] [“X”] the element is not interactive, as
the agent’s interactive set does not
contain B.

An agent is granted a permission if a permission (such as A, B, or X) configured in their Session

Description matches the permission-marker of the UI element in the application.

Note: In some circumstances an agent can be granted the default permission implicitly, but that
is not the same thing as having an empty set of permissions. In the above table, an empty
set of agent permissions means exactly that; a set of permissions containing only the default
permission may have been granted either implicitly or explicitly.

Parent and Child Permissions

An element can also inherit permissions through the UI hierarchy: UI elements that are a child of
a parent UI element inherit the permission marker of the parent, unless the child specifies a
permission marker of its own.

A child element can override its parent permission marker, but it will only be effective if the
agent’s viewable permission set contains the parent’s permission marker as well as the child’s
(the agent must be able to see the container in order to interact with an element inside it). This
allows the developer to make a child element interactive and the parent element not. An example
use of this could be a child button within a parent container, where only the button needs to be
interactive.

Permission Permission Agent Agent

marker set marker set viewable interactive
Result
on parent on child permission permission
element element set set

Agent can view and

interact with both
A [“A”] [“A”] parent and child
element. Child inherits
permission marker A.

Agent can view and

interact with both
A A [“A”] [“A”]
parent and child
element.

Agent cannot view or

A B [“A”] [“A”] interact with child
element marked with B.

Agent can view child

A B [“A”,“B”] [“A”] element but cannot
interact with it

Agent can view and

interact with the child
A B [“A”,“B”] [“B”]
element but cannot
interact with the parent.

A B [“B”] [“B”] Agent cannot view or

interact with child or

parent element as they
do not have the
parent’s permission
marker in their viewable
permission set. The
agent may not interact
with an element which
they cannot see, even
though they have the
appropriate permission
in their interactive
permission set.

Agent can view and

interact with both
parent and child
elements as they have
the default permission
[“default”] [“default”] in their viewable and
interactive permission
sets, and both parent
and child elements
implicitly have the
default permission.

B [“B”] [“B”] Agent cannot view or

interact with child
element, because the
parent has an implicit
default permission
marker, and they do not
have the default
permission in their
viewable permission
set. The agent may not
interact with an element
which they cannot see,
even though they have
the appropriate
permission in their

interactive permission
set.

Default Permission

You do not have to assign a permission marker to every UI element which you want agents to
view or interact with; every element which does not have or inherit a permission automatically
has the default permission marker.

Elements which have the default permission marker are viewable and interactive for any agent
which has the default permission. Any agent which has the default permission includes the
reserved word default among its set of permissions (as returned by
Agent.getViewablePermissions or Agent.getInteractivePermissions).

Not every agent has the default permission, and an agent might have the default permission in
its viewable permissions, but not in its interactive permissions.

Permissions in Web Views

The application can add permissions to HTML elements on a web page loaded with WebView. To
do this, call:

Assist.setPermissionForWebElementWithId(“X”, “ELEMENTID”, application);

where X is the permission marker to be set, ELEMENTID is the ID of the web page element,
and application is the Android Application object. This method provides similar functionality for
web pages loaded in WebView as is provided for native Android controls.

The application can remove all the permissions from all the elements on an HTML page by
calling:

Assist.resetAllWebPermissions(application);

where application is the Android Application object.

Note: The application cannot set permissions on elements within an iframe in an HTML page
loaded into a WebView; nor will elements in an iframe which have the assist-no-show class (see
the CBA Live Assist Web Developer Guide) be masked.

Internationalization
The strings which the CBA Live Assist Android SDK displays are in the
res/values/assist_strings.xml file. These strings can be internationalized in the usual way for
Android applications, by providing a separate set of string resources in a
res/values‑<lang>/assist_strings.xml file, where <lang> is the language code.

Integrating with FCSDK
When you call the Assist.startSupport method and provide a destination, but no correlationId or
sessionToken, in the AssistConfig, CBA Live Assist automatically starts a voice and video call
and a co-browse session with the agent, and automatically ends the call when the application
calls Assist.endSupport. If you want more control over the voice and video call than this, then
you should start the call using the FCSDK:

private Call call;

void init()
{
String sessionToken = getSessionToken();
UC uc = UCFactory.createUc(context, sessionToken, this);

uc.startSession();
}

public void onSessionStarted()

{
Phone phone = uc.getPhone();
call = phone.createCall(destination, true, true, this);
}

public void onStatusChanged(Call call, CallStatusInfo status)

{
if (status == CallStatus.IN\_CALL)
{
// Escalate call to co-browse
}
}

After the call is connected, you need to escalate that call to co-browse (see the Escalating an
existing call to include co-browse section). In order to control the call while it is in progress, the
application saves the Call object returned by phone.createCall, so that it can use it when
needed. For convenience of illustration, the code above implements the CallListener and
UCListener interfaces which receive information on the progress of session creation and call
setup.

See the FCSDK Developer Guide for more details of how to set up a call, and in particular, of
how to obtain a session token to use as the sessionId. It also gives details of what call control
features are available and how to use them.

Voice and Video Volume Control
To allow the volume keys on the device to control the volume of the voice and video functionality,
use the following call in the onCreate method in any Activity or Fragment that makes use of the
voice and video functionality:

setVolumeControlStream(AudioManager.STREAM_VOICE_CALL);

Using CBA Live Assist without Voice and
Video
If the built application does not require voice and video functionality, you can exclude the
following libraries:

fusionclient-android-sdk2.x.x.jar file

andarmeabi-v7a

This has the advantage of reducing the size of the application.

To create a CBA Live Assist session without voice and video, provide a correlation ID (using
setCorrelationId), but without specifying an agent name (using setAgentName(..)) when
configuring the AssistConfigBuilder.

The application can then call Assist.startSupport as described in the Starting a Support Session
section. You do not need to call setMediaMode on the AssistConfigBuilder when carrying out a
CBA Live Assist-only session. It will be necessary to explicitly call AssistSDK.endSupport to
end the session. Note:

The correlation ID needs to be known to both parties in the call, and needs to be unique
enough that the same correlation ID is not used by two support calls at the same time. The
application developer must decide the mechanism by which this happens, but possible ways
are for both parties to calculate a value from data about the call known to both of them, or
for one side to generate it and communicate it to the other on the existing communication
channel. There is also a REST service provided by CBA Live Assist which will create a
correlation ID and associate it with a short code; see the Informing the Agent of the
Correlation ID section.

The CBA Live Assist SDK throws an Exception if the application tries to make a voice and
video call without the fusionclient-android-sdk2.x.x.jar and armeabi-v7a libraries present,
and will show the following message in the logs:

RuntimeException—CSDK library not found, cannot create call. Please check the classpath
and/or refer to the documentation for more information.

To remedy this, either add the libraries to the application, or create a CBA Live Assist session
without voice and video.

Informing the Agent of the Correlation ID

CBA Live Assist gives some help to the application in informing the agent of the correlation ID;
it can create a short code and associate it with the correlation ID when it creates the session,
and the client can send the short code out-of-band to the agent:

The advantage of communicating a short code, rather than communicating the correlation ID
directly, is that the short code generated by the CBA Live Assist server is guaranteed to be both
unique during the communication process, and short enough for the client to communicate by
voice (or whatever other out-of-band communication channel is in use) without error. Note:

The short code expires 5 minutes after creation; it should therefore be used as soon as
possible after being created.

Once a short code has been used by both agent and consumer to communicate a
correlation ID, it is discarded, and may be used by a different agent and consumer to
communicate a different correlation ID.

Including a Second Agent

There is a second scenario in which the short code REST service can be used when there is no
existing call between the two parties. If an agent is in a co-browse session with a consumer and
wishes to include a second agent in the same co-browse session, the agent already knows the

correlation ID of the CBA Live Assist session, and can use it in the initial call to the REST
service, to associate that correlation ID with a newly created short code:

The second agent application uses the short code in exactly the same way as before to connect
to the same co-browse session as the first agent and the consumer.

Consumer Session Creation
A client application needs an FCSDK Web Gateway session token and a correlation ID to
establish a co-browsing session. When the application calls startSupport, CBA Live Assist uses
a built-in mechanism to create a session token for the voice and video call, and associates it with
a correlation ID for the co-browse. The built-in mechanism provides a standalone, secure
mechanism for creating a session token and a correlation ID, but the process is not integrated
with any pre-existing authentication and authorization system, and assumes that if a client can
invoke startSupport, it is permitted to do so.

If you wish to integrate your CBA Live Assist application with an existing authentication and
authorization system, you can disable the built-in mechanism (by setting the Anonymous
Consumer Access setting to disabled using the Web Administration service; see the CBA Live
Assist Overview and Installation Guide for how to do this), and replace it with a bespoke
implementation which uses the existing system to authorize and authenticate the client.

Once you have authenticated and authorized the application using the pre-existing system, the
application needs to create a session token (see the Fusion Client SDK documentation for
details of how to create the session token) and associate it with a correlation ID.

Session Token Creation

A bespoke implementation needs the following general steps:

1. Create a Web Application that can invoke the Session Token API REST Service, exposed
by the FCSDK Web Gateway.

2. Provide the appropriate Fusion Client SDK (if in use) configuration in a JSON object (the
session description).

3. Add CBA Live Assist-specific data to the session description:

AED2.metadata.role

This should be set to consumer

AED2.metadata.auditName

Optional name to use to identify the consumer in event log entries (see the CBA Live Assist
Overview and Installation Guide for details about event logging.

AED2.allowedTopic

A regular expression which limits the correlation IDs which the session token can be used to
connect to. A value of .* allows the session token to be used to connect to any support session
with any correlation ID. For security reasons, we recommend that this should be set to the value
of the correlation ID which will actually be used:

{
...
"voice": {
...
},
"aed": {
"accessibleSessionIdRegex": "customer-ABCDE",
...
},
...
"additionalAttributes": {
"AED2.allowedTopic": "%s",
"AED2.metadata": {
"role": "agent",
"name": "Example Agent",
"permissions":
{ "viewable": \["test", "default"\], "interactive": \["go", "text", "default"\]
}
}
}
...
}

4. Request a session token by sending an HTTP POST request to the Session Token API,
providing the session description in the body of the POST.

For steps 1, 2, and 4, see the FCSDK Developer Guide, Creating the Web Application.

Note: The FCSDK Developer Guide documents both voice and aed sections - at least one of
these must be present to create the session token. However, if the session description includes a
voice section (which it must if voice and video functionality is required), then only the AED2
entries are needed for CBA Live Assist functionality. If voice and video functionality is not

needed, and there is no voice section, then there must be an aed section as well as the AED2
section entries.

System Dialog Boxes
Due to limitations imposed by Android, CBA Live Assist cannot show to the agent any dialog
boxes generated by Android itself on the consumer device, such as the following items:

Alert boxes

Keyboard

Menus generated by HTML (for example, the popup menu generated by the HTML <select>
element).

You should consider whether the agent needs to see those elements, and consider alternative
implementations on the consumer side, such as JavaScript and CSS.

Password Fields
When entering a password into a text field on an Android device, it briefly displays the character
that has been entered before replacing it with a dot. As a user’s device screen is being replicated
and displayed to an agent, the agent may be able to see the password as it is being entered.
Consequently, we recommend that you mask fields that can contain sensitive information using
the built-in masking capabilities provided by the CBA Live Assist SDK.

See the Excluding elements from a view section.

HTML 5 Canvas Drawing is not Co-browsed
to Agent
Due to a limitation of hardware accelerated rendering of Android Web Views, HTML5 <canvas>
elements loaded in a WebView are not replicated to the agent. However, the canvas content is
replicated if a WebView is configured to be software rendered.

Before loading the WebView, you can set the layer type for the WebView to software:

WebView.setLayerType(View.LAYER_TYPE_SOFTWARE, null);

Guidance for hardware and software rendering can be found in the Android documentation.

Media is Transmitted when the App is in the
Background
When your application goes into the background, Android continues to transmit any media
(voice, video, and screenshare). This is Android defined behavior, but may not be what you want.
You may want to pause the co-browse session whenever the application goes into the
background.