Implementing Khoros Brand Messaging in your Website & Mobile Apps - An Introduction
This document is a short technical implementation primer on Khoros Brand Messenger. Although Khoros Brand Messenger is a relatively new channel for Khoros, we OEM the messaging infrastructure from smooch.io - they provide a mature and proven infrastructure. The Khoros web and mobile SDKs we provide are at the core white-labeled versions of smooch’s SDKs.
We have not yet produced Khoros branded tier 1 documentation, so we currently require early access customers to refer to the Smooch documentation. As we continue to evolve our offering, we'll offer more and more branded documentation, but currently the best primer on using the SDKs can be found here:
Each has a link to the specific API documentation at the top.
In addition to the documentation, there are also developer discussions about Smooch on the web, along with sample projects on github, so it is good for your technical teams to know that it is Smooch (and google accordingly).
Over time we expect to add functionality in our SDK on top of smooch, so you will definitely want you to be using our white-labeled SDKs from the beginning. The white-labeled web SDK is currently hosted in a favorable way for web-development, but the white-labeled mobile SDK are not yet. See the appendix at the bottom of this article.
As soon as you are ready, you can begin using your dev environment and have your team test the messaging widget. We can cover those details and understand your plans in a 30-minute introductory call with you and your technical lead. We will review the notes below. Please contact your Khoros account representative to set this up.
There is a lot possible, so please posts questions here and we will answer.
User Interface
The SDK provides three options for the User Interface:
- Completely OOTB UI - you initialize the SDK, and the SDK renders the floating messaging bubble in the lower-right and the messaging pop-up. You control the icon, messaging colors, copy-text, and background. This only applies to Web - the mobile SDKs require that you implement the button (or other user-action) that initiates messaging (see the next item)
- Custom Initiation, OOTB Widget - you render your own button (floating or not) and/or user action that initiates messaging, and determine where the SDK renders the widget (you provide the id of a div), and the SDK renders the messaging window. You control colors, copy-text, and background. This is the standard when using the mobile SDKs, and the approach for web if you want something other than the floating button in the lower right.
- Completely Custom UI - the SDK provides APIs that allow you to render the entire messaging experience yourself and customize the behavior. If you render the entire interface yourself, you take responsibility to render all possible structured messages - and hence this option in its entirety, is uncommon, but..
The SDK APIs are often combined with the previous options to provide a full solution. For example, the APIs allow you to add meta-data to posts and/or to the messaging author, and these values can be used on the backend. Or a message sent to the customer could contain meta-data that the UI interprets to take some action.
Unauthenticated and Authenticated Users
The SDK can be used with unauthenticated users and authenticated users. After initializing the SDK, a session is unauthenticated until the SDK login method is called. After this, it is an authenticated session and the conversation will be visible in future authenticated sessions for the same user.
- Unauthenticated sessions - The SDK generates an id for unauthenticated users.
- On mobile devices, this is tied to the installed app (so an unauthenticated user on a mobile device will see their history until they uninstall and reinstall the app.
- On the web, the id is by default stored in localStorage (if available) meaning future messaging sessions in the same browser will show history. If not available, or if you specify in the SDK settings, sessionStorage will be used (this is most appropriate on shared computers). You have the choice, and you could even ask the user - you’ve probably seen a “is this a shared computer?” question on some websites. This is documented here with an explanation of local and session storage here.
- Authenticated sessions - once a session is authenticated, the end-user will see all previous messaging history they have had (from any SDK) as long as they are the same user (note, there is an option in Khoros to remove the ability for an authenticated user to see their history). The user is considered the same if you pass the same userId to the login method, so the userId is often the unique ssoId, or user identifying, provided by your authentication infrastructure. And the userId needs to be encrypted in a standard JWT token encrypted with a secret we provide you. The JWT needs to be generated securely (for example, server-side with the web SDK). Documentation on generating JWTs is here and a broader discussion of how the SDK uses them is here.
In general, messaging embedded in a mobile app is generally authenticated because the user is logged into the mobile app, but nothing prevents you from offering messaging when the user is not authenticated - for example, on the login page.
Note - As an example of a clever use-case using the SDK APIs, if you exposed messaging on the login-page of your app, and your agents have a manual way to validate a user, your app could allow your agents to send a “magic message” to an unauthenticated user that triggers a “set a new password” flow inside your app.
Also, a messaging interaction with an end-user can start unauthenticated and transition to authenticated if you call the login method part-way through the messaging interaction. It seamlessly transitions for the end-user with any history for the authenticated user appearing.
Push Notifications
Yes, they can be configured with the native Mobile SDKs, and with the web SDK, there is by default a sound notification and unread message badge that appears (and you could implement any other notification scheme you want with the SDK APIs).
Implementation timeframe
It is really dependent on your development team and their ability to focus on implementing messaging.
One customer implemented messaging in their existing mobile app (iOS and Android versions) using the documentation outlined above with little involvement from us from start to production release in ~2wks. The only dependency on Khoros is getting the initial values for messaging (and appId and secret for generating the JWT), and configuring push notification certificates in our backend. Realistically, 2-3 wks is probably the shortest reasonable dev cycle to get to production.
Another customer implemented authenticated web-messaging in ~1wk for an internal use-case. The only back-end development is setting up a mechanism to generate the JWT to identify the user.
Region Configuration
Production environments of the messaging infrastructure (and Khoros Care) for EU customers is hosted in the EU. For this reason, you need to provide EU-1 for the region when you initialize the SDK.
All development environments are hosted in the US and no region needs to be specified when you initialize the SDK.
Summary & Next Step
In a nutshell, the main steps to implement messaging in your mobile app or website is:
- include the SDK
- initialize the SDK, and if needed, call the login method (you must create an encrypted jwt with a secret we provide).
- have the SDK render the messaging widget when desired
- (mobile only) configure push notifications
Next Steps -As soon as you are ready, you can begin using your dev environment and have your team test the messaging widget. We can cover those details and understand your plans in a 30-minute introductory call with you and your technical lead. We will review the notes below. Please contact your Khoros account representative to set this up.
Appendix: Accessing the SDKs
Over time we expect to add functionality in our SDK on top of smooch, so you will definitely want you to be using our white-labeled SDKs from the beginning. The white-labeled web SDK is currently hosted in a favorable way for web-development, but the white-labeled mobile SDKs are not yet. You can download all white-labeled SDKs from here, but read the notes below.
Web Messenger Initialization
The web SDK has a web-loader hosted at https://messaging.app.lithium.com/loader.json Below is a sample that uses the script-tag method outlined here using this web loader.
!function (e, n, t, r) {
function o() { try { var e; if ((e = "string" == typeof this.response ? JSON.parse(this.response) : this.response).url) { var t = n.getElementsByTagName("script")[0], r = n.createElement("script"); r.async = !0, r.src=e.url, t.parentNode.insertBefore(r, t) } } catch (e) { } } var s, p, a, i = [], c = []; e[t] = { init: function () { s = arguments; var e = { then: function (n) { return c.push({ type: "t", next: n }), e }, catch: function (n) { return c.push({ type: "c", next: n }), e } }; return e }, on: function () { i.push(arguments) }, render: function () { p = arguments }, destroy: function () { a = arguments } }, e.__onWebMessengerHostReady__ = function (n) { if (delete e.__onWebMessengerHostReady__, e[t] = n, s) for (var r = n.init.apply(n, s), o = 0; o < c.length; o++) { var u = c[o]; r = "t" === u.type ? r.then(u.next) : r.catch(u.next) } p && n.render.apply(n, p), a && n.destroy.apply(n, a); for (o = 0; o < i.length; o++)n.on.apply(n, i[o]) }; var u = new XMLHttpRequest; u.addEventListener("load", o), u.open("GET", "https://messaging.app.lithium.com/loader.json", !0), u.responseType = "json", u.send()
}(window, document, "khorosMessaging", <appId provided to you>);
