Basic Setup to Test the Mobile SDK

As you integrate Digital Experience (Digital) chat into your mobile app, you may need to test certain features or functionality. This page explains the minimum setup required to let you start testing. Some of the tasks on this page require an administrator account in CXone Mpower. If you do not have an administrator account, you may need to work with your manager or a CXone Mpower representative.

Access to CXone Mpower is controlled by roles. Roles have individual permissions that allow users to access apps like an agent application, or create and manage things like a chat channel.

Prerequisites

Download the SDK package for your desired platform (Android and iOS).
Add dependencies for the maven coordinates. This is explained in the repository README files.
You or an administrator must have CXone Mpower access:
- An agent account in CXone Mpower with the following ACD permissions:
  View permissions
  The following lists the minimum permissions for an agent to handle digital interactions. You can enable additional permissions if necessary.
  
  Agent Permissions:
  - Launch Max or Launch Agent depending on which agent application your organization uses
  - CRM Module
  Digital Engagement Permissions:
  - Care Module
  - CRM Module
- A CXone Mpower administrator account with the following ACD permissions:
  View permissions
  The following lists the minimum permissions for an administrator. You can enable additional permissions if necessary. For example, you must enable the Satisfaction Surveys permission to configure satisfaction surveys.
  
  Digital Engagement Permissions:
  - Settings Module
  - User and Role Settings
  - Channels Settings
  - Custom Fields Settings
  - Agents Settings
  - Intelligent Routing Queues
  Contact Settings Permissions:.
  - Skills: View, User Assignment, Edit, Create
  Studio Permissions:
  - Studio Scripts: Create/Edit
Identify your CXone Mpower deployment region and provide the environment code to your developer. Contact your Account Representative for more information.

CXone Mpower Setup

These steps must be performed in CXone Mpower with an administrator account.

Set up a chat messaging channel.
Find the channelId and brandId for your desired chat messaging channel.
1. In CXone Mpower, click the app selector and select ACD.
2. Go to Digital > Points of Contact Digital > Chat > locate your chat channel > Initialization & Test.
3. Just before the closing script tag, locate the cxone declaration, which looks like this: cxone('chat', 'init', 1132, 'chat_6fed4507-8cf3-443a-87a5-820981d1752b');.
4. Save the four-digit number, which is your brandId.
5. Save the longer alphanumeric string, which is your channelId.
6. Provide these IDs to your developer.

Complete Getting Started

These steps are performed by the developer.

Work through the getting started content for the platform you're developing on. The repository README files (Android iOS) contain this getting started information. These help you set up the necessary dependencies and synchronize the SDK with your code editor. You can skip certain sections of the getting started, depending on your needs. For example, you can skip setting up any advanced features like OAuth or push notifications.
Initialize the chat instance:
- Android: Use Chatbuilder to provide your environment region, brandId, and channelId. You must also call connect() on the chat instance.
  View Android code example
```
val config = SocketFactoryConfiguration(
	CXOneEnvironment.YourRegion,
	yourBrandId,
	yourChannelId
)
val myChatStateListener = object : ChatStateListener() {
	override fun onReady() {
		// TO DO - Chat instance is ready for usage by end-user, use chat instance for chat
	}
}
cancellable = ChatBuilder(context, config)
	.setDevelopmentMode(BuildConfig.DEBUG)
	.setAuthorization(yourAuthorization) // only for OAuth
	.setUserName("firstName", "lastName") // only for OAuth
	.setChatStateListener(myChatStateListener) // notifies the app when the WebSocket is connected
	.build { chat ->
		// Chat instance will be delivered in this callback once connection is established
		// TO DO save chat instance
}
```
  If the connection was unsuccessful and build did not return the chat instance, check your configuration. The server may have rejected your request. Refer to ChatBuilder.OnChatBuiltCallback.
  
  The build method asynchronously creates an instance of the chat, which is already connected to the back end. In case of a connection error, the builder schedules a connection retry attempt. You can cancel this process according to its requirements with the Cancellable instance. This returns from the build method call.
  
  The chat instance maintains an open socket connection to the backend until chat.close() is called or the application process is terminated. Your app must close the chat when the user leaves.
  
  The WebSocket should only run when necessary. Only call ChatBuilder for active chat conversations and analytics purposes.
- iOS: Use connect() to provide your environment region, brandId, and channelId.
  View iOS code example
```
try  await CXoneChat.shared.connection.connect(
	chatURL: configuration.chatUrl,
	socketURL: configuration.socketUrl,
	brandId: configuration.brandId,
	channelId: configuration.channelId)
```
  The main class for the mobile SDK in iOS is CXoneChat.
  
  The WebSocket should only run when necessary. Only call connect() for active chat conversations and analytics purposes.
  
  Register onError(_ error:) to be able to handle errors that occur during the thread load process. When there are no threads to load, the SDK returns RecoveringThreadFailed which is a soft error.
Set up logging to view any reported errors.

The Android SDK provides a logger framework that forces the SDK to log to Logcat. You can also use the default Android logger. These are set up with ChatBuilder.

The iOS SDK has the LogManager class to facilitate logging. You can also reference CXoneChatError to view all the errors that you may receive.
Set up either single-thread In a single-threaded app, each contact has one chat thread that handles any interaction they have with your organization. or multi-thread In a multi-threaded app, contacts can create as many threads as they want to discuss new topics. These threads can be active at the same time. handling. A single thread setup may be simpler for testing purposes. Be sure to check the single-thread case studies in the both Android and iOS SDK repositories.

Testing Tips

Android

Keep in mind the following:

Follow the single-thread or multi-thread case studies and try to replicate sending a simple message. For multi-thread, try to also create a secondary thread and send a simple message to see if the thread updates with the new message.
If necessary, you can skip implementing a UI and focus on testing the exchange of messages.
ChatStateListener informs the application about any runtime exceptions, errors, or a state changes. You can reference CXOneException.kt and ChatStateListener.kt for more information. Be sure you test for any exceptions or errors.
Some exceptions or errors may result from something under your control like AuthorizationError or ServerCommunicationError. However, exceptions like InvalidStateException or InvalidParameterException indicate an error on your side.

iOS

Follow the single-thread or multi-thread case studies and try to replicate sending a simple message. For multi-thread, try to also create a secondary thread and send a simple message to see if the thread updates with the new message.
If necessary, you can skip implementing a UI and focus on testing the exchange of messages.