In-App Messaging Guide
This guide will show you how to integrate the Webex Connect In-App Messaging capability into your iOS application.
Please ensure you have integrated the In-App Messaging Module by following the Quick Start Guide.
Overview of In-App Messaging
In-App Messaging allows bi-directional communication between the Webex Connect platform and your mobile application. Messaging is thread-based, meaning all messages are associated with a specific thread. A thread can be viewed as a chronological sequence of messages presented as a conversation. An end user can participate in one or more threads.
Types of Threads
Webex Connect supports two types of threads:
Conversation Threads: These threads are used for bi-directional communication, making them well-suited for chat experiences.
Announcement Threads: These threads are uni-directional, from the platform to the mobile app, and are ideal for service messages, alerts, and offers.
Messages are delivered via real time connection between the SDK and the Webex Connect message broker. Messages that are published when the real time connection is not active, will be held at the broker for a maximum of 24 hours, and will be delivered once a connection has been established. Messages that are not delivered within the 24 hour period will be removed from the broker and will not be delivered via the real time connection, although can still be retrieved from the Server-Side Inbox (see below).
Our Server-Side Inbox feature persists threads and messages within the Webex Connect platform for later retrieval via API. Data is persisted for a period of 30 days, although this can be adjusted upon request via your account manager. The maximum data retention period is 1 year.
Note
The Server Side Inbox feature must be enabled within your app asset configuration. If the feature is not enabled, any messages that are not delivered via real-time connection within 24 hours of publication, will be lost.
Below are the steps, you need to complete to enable In-App Messaging in your app.
a. Establishing a connection
b. Monitoring Messaging Connection Status
c. Receiving messages
d. Creating threads
e. Publishing messages
f. Closing the connection
a. Establishing a connection
In App Messaging uses its own dedicated connection, therefore you must establish the connection with the Webex Connect platform before messages can be received. Connection is established by invoking the connect method as shown below.
var inApp = InAppMessagingProvider.instance
try inApp.connect()
id<InAppMessaging> inApp = [InAppMessagingProvider instance];
[inApp connect:error];
Note
You only need to call the
connectmethod once, after which the SDK will manage the connection for you, even between app restarts. The SDK will stop managing the connection if thedisconnectmethod is called.
b. Monitoring Messaging Connection Status
The SDK exposes the current status of the messaging connection via the InAppMessagingDelegate protocol.
As connection status changes the SDK raises events to notify the change to your application code. To receive these events in your application, you need to set the delegate and implement the didChangeConnectionStatus method from the InAppMessagingDelegate protocol.
func setInAppDelegate() {
var inApp = InAppMessagingProvider.instance
inApp.delegate = self
}
func didChangeConnectionStatus(_ connectionStatus: WebexConnectInAppMessaging.ConnectionStatus) {
//didChangeConnectionStatus method monitors the connection status using WebexConnectInAppMessaging.ConnectionStatus and updates the application's UI or internal state based on the current status.
var connectionString = "Not Connected"
var connectionStatusColor: Color = .red
// Update connection status string and color based on the current status
if connectionStatus == .connected {
//If the status is .connected, the connectionString is set to "Connected" and connectionStatusColor is set to green.
connectionString = "Connected"
connectionStatusColor = .green
} else if connectionStatus == .connecting {
//If the status is .connecting, the connectionString shows "Connecting..." and connectionStatusColorturns yellow.
connectionString = "Connecting..."
connectionStatusColor = .yellow
} else {
//For any other status (e.g., disconnected), the connectionString shows "Not Connected" and the color is red.
connectionString = "Not Connected"
connectionStatusColor = .red
}
}
- (void)setInAppDelegate {
id<InAppMessaging> inApp = [InAppMessagingProvider instance];
inApp.delegate = self;
}
- (void)didChangeConnectionStatus:(ConnectionStatus)connectionStatus {
//didChangeConnectionStatus method monitors the connection status using WebexConnectInAppMessaging.ConnectionStatus and updates the application's UI or internal state based on the current status.
NSString *connectionStatusString;
UIColor *connectionStatusColor;
switch (connectionStatus) {
case ConnectionStatusConnected:
connectionStatusString = @"Connected"; //If the status is .connected, the connectionString is set to "Connected" and connectionStatusColor is set to green.
connectionStatusColor = [UIColor greenColor];
break;
case ConnectionStatusConnecting:
connectionStatusString = @"Connecting..."; //If the status is .connecting, the connectionString shows "Connecting..." and connectionStatusColorturns yellow.
connectionStatusColor = [UIColor yellowColor];
break;
default:
connectionStatusString = @"Not Connected"; //For any other status (e.g., disconnected), the connectionString shows "Not Connected" and the color is red.
connectionStatusColor = [UIColor redColor];
break;
}
NSString *logMessage = [NSString stringWithFormat:@"InApp didChangeConnectionStatus: %ld", (long)connectionStatus];
NSLog(@"%@", logMessage);
}
Note
Mobile data connections can be unreliable, therefore it is normal for disconnects to occur. In case of a disconnection the SDK will automatically re-establish the connection for you.
c. Receiving messages
As messages are received by the SDK they are emitted via InAppMessagingDelegate protocol. To handle received InApp messages, you need to set the delegate and implement the didReceiveInAppMessage method from the InAppMessagingDelegate protocol.
var inApp = InAppMessagingProvider.instance
inApp.delegate = self
// Handle received In-App messages
func didReceiveInAppMessage(message: InAppMessage) {
// Process the received message
print("Received in-app message: (message)")
// Implement additional message handling logic as needed
}
id<InAppMessaging> inApp = [InAppMessagingProvider instance];
inApp.delegate = self;
// Handle received In-App messages
- (void)didReceiveInAppMessage:(InAppMessage *)message {
// Process the received message
NSLog(@"Received in-app message: %@", message);
// Implement additional message handling logic as needed
}
d. Creating threads
To create a new thread, instantiate an InAppThread object, set the required data fields, and invoke the createThread method.
let newThread = InAppThread()
newThread.title = "title"
newThread.category = "category"
InAppMessagingProvider.instance.createThread(newThread) {
(thread, error) in
if let error = error {
print("Error while creating thread: (error.localizedDescription)")
}
else if let thread = thread {
print("Created thread: (thread)")
}
}
InAppThread *newThread = [[InAppThread alloc] init];
newThread.title = @"title";
newThread.category = @”category”;
[[InAppMessagingProvider instance] createThread:newThread completionHandler:^(InAppThread *thread, NSError *error)
{
if (error == nil)
{
NSLog(@"created thread: %@", thread);
}
else
{
NSLog(@"error while creating thread: %@",
[error localizedDescription]);
}
}];
e. Publishing messages
To publish a message, create an instance of InAppMessage, set the required data fields, and call the publishMessage method. Messages must be assigned a valid InAppThread instance, which is obtainable by creating a new thread, fetching existing threads, or from an existing InAppMessage.
var inApp = InAppMessagingProvider.instance
let message = InAppMessage()
inApp.publishMessage(message) { error in
}
id<InAppMessaging> inApp = [InAppMessagingProvider instance];
InAppMessage *message = [[InAppMessage alloc] init];
[inApp publishMessageWithMessage:message completion:^(NSError *error) {
if (error) {
// Handle error
NSLog(@"Error publishing message: %@", error.localizedDescription);
} else {
// Handle success
NSLog(@"Message published successfully");
}
}];
f. Closing the connection
The In-App Messaging module will normally manage the messaging connection for you, automatically connecting and disconnecting as your app transitions between background and foreground states. However, if you wish to disconnect and prevent the In-App Messaging module from re-establishing the connection, you may call the disconnect method.
Implementation:
var inApp = InAppMessagingProvider.instance
try inApp.disconnect()
id<InAppMessaging> inApp = [InAppMessagingProvider instance];
NSError **error;
[inApp disconnect:error];
With this you have successfully integrated the In-App Messaging module within your app.
Updated about 1 month ago