Integrating unblu chat in your mobile app
1.1. General approach
Since the unblu technology is purely web-based, it can be integrated into native mobile apps (iOS and Android) using WebViews. To make this possible the following things must be done:
- Setup app with WebView
- Integrate unblu example HTML, JS and CSS files into the project
- Add the initialisation of the WebView into the App
- Add special configuration to the server
This documentation will go through these steps with an Android application as an example. Integrating the chat into an iOS app should work mostly the same with small adaptions.
This is to be regarded as an example. It can be used as base for a real project but must be adapted to fit the exact needs of the project and app.
1.2. What it looks like
Here are some screenshots of the Android example app.
2. Prerequisites of the native app
To start off an app is required that has an Activity or Fragment which holds a WebView. Basically the WebView can be placed anywhere however it is recommended to use the WebView as only child of the Activity or Fragment and give it all available screen space to avoid performance problems and guarantee that the content is large enough to be usable. The example below can be used as layout.xml for your Activity or Fragment.
The second step is to setup the WebView so that it will work with unblu.
This is all that is needed to setup the WebView to be able to run unblu. The next step is to integrate and load unblu in the WebView.
3. Integrating unblu into the app
3.1. Integration approach
3.1.1. Loading resources from a web server
- Very flexible since changes to the scripts can be done server side and don't need an app update.
- App size is not affected since no additional files are added.
- Slower since the files first have to be retrieved from the internet
- Slightly less secure since the files are loaded from the internet
3.1.2. Embedding resources in the app
- Faster since some of the files are loaded directly from the device
- Slightly more secure since the files loaded are directly located in the app
- Less flexible: all changes to the resources on the device need an update of the app.
- Size may become larger because the files are embedded.
These are the files needed to integrate unblu into the app.
3.2. Main HTML file
The main html file is the file that is initially loaded in the WebView and will run, maintain and show the chat. Its most important job is to load the correct script files that start the session. Additionally it should display a loading screen until the chat session is ready.
Corresponding to the main.html the main.js file does the actual initialization of the unblu application and provides functions that can be called from the mobile app as well as callbacks that should be implemented in the mobile app and provided to the WebView. This serves as an example and can be changed and extended to the needs of the actual mobile application.
3.3.1. Unblu initialisation
To allow the mobile application to control which unblu server and which unblu API token should be used, the main.js script expects its backing html file to be loaded with query parameters defining these.
So when loading the html file initially these query parameters must be added or the unblu starter script can't be loaded.
3.3.2. Function API
The following functions may be called by the mobile app by sending them to the WebView
Initiates a chat session with the given username.
If a previous session was not terminated it will try to restore it. (Delete cookies to avoid this behaveiour)
Note: Must be called after the "document-ready" event.
@param username Username to be used for the chat session
Terminates the current session.
If no session is active, nothing will be done.
The following functions should be implemented by the mobile application and made visible to the WebView under the following prefix:
Called when the DOM document-ready event occurs.
Note: this is used instead of using the WebViewClient.onPageLoaded() callback
since there are issues of it being called multiple times for pre Lollipop WebViews.
Called when a session is being established and a previous session could be restored.
Called when no agent is available for chat.
Called when a new session has successfully been started
Called when the current session has ended. (Either through abort or terminate)
Called for any error that occurred
@param message The error message
Should retrieve and return the localised text for the given key.
This enables content of the WebView to display localised texted provided by the app.
@param name Key for the string resource to retrieve.
@return Localised string representing the resource.
3.4. Additional files
The additional files will not be explained in detail here. Look into the source code to see what they do exactly. Here is a brief overview of what they are for:
- unblu-snippet.js and unblu-chat.js utilise the public unblu api to provide the functions used in the main.js. They can also be modified to fit the needs of the specific project und unblu setup.
- main.css contains styles for formatting and laying out the main.html page e.g. displaying and animating the loader. This also serves as an example that should be adapted.
- unblu-overwidden.css hides and modifies some of the unblu user interface items which are not needed or not wished in the mobile chat scenario. This file should not be adapted.
3.5. Embedding the files into the app
To embed the discussed file into the app and make them available for the WebView, they must be copied into the projects assets folder. To keep the folder structure clean it is advised to use subfolders for html, js, img, style. etc. files.
How these files can be accessed will be discussed in the next chapter.
4. Binding unblu and the mobile app
4.1. Providing callbacks to the WebView
The example application holds examples of what may be done in the callback methods. See:
4.2. Loading the main.html
Now the main.html file that we placed in the assets folder must be loaded into the WebView which will automatically initialise the unblu environment and then wait for an API-call to start the chat. Two things have to be taken into account when doing this.
1.) Query parameters
As described in the previous chapter, for this example, the main.html has to be loaded with query parameters for the unblu server and the unblu API key.
This may be done differently for real projects depending on how server and API key are retrieved.
2.) Base URL
Since we are loading a local html file we do not have a valid origin if we just load it with a simple:
Without a valid origin we will have problems with cross-document messaging used by unblu as well as with communication with the unblu server which requires a valid origin.
To overcome these problems, the html file is loaded with a base URL which makes it act, like it was provided from the given URL and therefore provides a valid origin. This URL can be any existing or un-existing URL.
A second reason of why this base URL is important is the filtering of Chat requests in the unblu agent desk. The base URL provided here will be displayed in the Chat queue and allows filtering. This can be used as a powerful tool to filter only the chat requests from the mobile app.
4.3. Starting a chat session
After the main.html is loaded the last step needed is to actually start a chat session which must be initiated from the mobile application.
This marks the last step needed on the client (app) side. Use the callbacks and API methods to observe and control the session flow.
5. Configuring the server
Unblu allows different configurations to be applied for different scopes. One of the scope options is the domain that the visitor is on. Since we are using a base URL for our mobile app, this allows us to do specific configurations for our mobile application using the domain scope.
The following specific configuration flags must be set for the chat to be displayed correctly in the mobile app. As of this documentation (unblu v4.0.0RC9) some of them are unofficial, not supported configuration properties that may change un-documented and should be used at own risk.
For more details on how the configuration can be integrated into the product please refer to the documentation of Advanced Unblu Server Configuration.
6. Example Application
A compilation of all described steps can be found in the attached Android Unblu Chat Demo app. If the server is setup as described above it can be used out of the box simply by adding the correct configuration in the
The app is based on the Android gradle build system and can be imported and used into Android Studio .
GitHub link: https://github.com/unblu/example-mobile-android-chat