In-App Messaging Guide

This short guide will show you how to wire up an Android application to use the imiconnect In App Messaging capability.

In App Messaging allows bi-directional communication between the imiconnect platform and your mobile application. Messaging is thread based, which means all messages are associated with a thread, an end user may participate in one or many threads.

IMIconnect supports two types of threads, Conversation and Announcement. Conversation threads are used for bi-directional communication so are well suited to chat experiences. Announcement threads are uni directional, from platform to mobile app, and are ideal for items such as service messages, alerts and offers.

📘

Note

The Core SDK is only concerned with message transport and not message display, but we do offer a UI SDK that contains a suite of customizable UI components.

Establishing a connection
Listening for connection status events
Receiving messages
Creating threads
Publishing messages
Closing the connection

a. Establishing a connection

In App Messaging uses its own dedicated connection, therefore you must establish the connection with the imiconnect platform before messages can be received. Connection is established by invoking the ICMessaging.connect method.

ICMessaging messaging = ICMessaging.getInstance();

try
{
  messaging.connect();
}
catch (ICException e)
{
  //An exception can occur if In App Messaging is not enabled for your app asset or if the device is not registered with the SDK.
  Log.e("Connect", e.toString());
}

📘

Note

You only need call the connect method once, after which the SDK will manage the connection for you.

b. Listening for connection status events

The SDK exposes the current status of the messaging connection via the ICConnectionStatus enumeration.
As connection status changes the SDK raises events to notify the change to your application code, to receive these events in your application either:

  1. Create a receiver class extending ICMessagingReceiver and override the onConnectionStatusChanged method. -- OR --
  2. Implement and register an ICMessagingListener
public class MyReceiver extends ICMessagingReceiver 
{  
  ...
    
  @Override
  protected void onConnectionStatusChanged(final Context context, final ICConnectionStatus status, final ICException e) 
  {
    Log.d("ConnectionStatusChanged", "Status : " + status.toString());
  
    if (e != null) 
    {
      Log.e("ConnectionStatusChanged", "Exception : " + e.toString());
    }
  }
}


ICMessaging.getInstance().registerListener(new ICMessagingListener()
    {
        ...

        @Override
        public void onConnectionStatusChanged(final ICConnectionStatus icConnectionStatus, final ICException e)
        {
      Log.d("ConnectionStatusChanged", "Status : " + status.toString());
  
      if (e != null) 
      {
        Log.e("ConnectionStatusChanged", "Exception : " + e.toString());
      }
        }
    });

📘

Note

Mobile data connections can be unreliable, therefore it is normal for disconnects to occur and the SDK will automatically re-establish the connection for you.

c. Receiving messages

In-App messages are received via the onMessageReceived method of a custom ICMessagingReceiver subclass or ICMessagingListener implementation, just like connection status events.

Implement your custom receiver or listener as follows:

public class MyReceiver extends ICMessagingReceiver 
{
    @Override
    protected void onMessageReceived(final Context context, final ICMessage message) 
    {
        Log.d("MessageReceived", message.getMessage());
    }
}

ICMessaging.getInstance().registerListener(new ICMessagingListener()
{
    @Override
    public void onMessageReceived(final ICMessage icMessage)
    {
        Log.d("MessageReceived", message.getMessage());
    }

    @Override
    public void onConnectionStatusChanged(final ICConnectionStatus icConnectionStatus, final ICException e)
    {
        //For InApp Messaging connection events
    }
});

d. Creating threads

In-App Messaging within imiconnect is thread based, this means that all messages are associated with a particular thread. The SDK exposes thread data via the ICThread class. To create a new thread within the imiconnect platform instantiate a ICThread object, set the required data fields and invoke the createThread method.

ICThread thread = new ICThread();
                
thread.setTitle("title");
thread.setCategory("category");
                
ICMessaging.getInstance().createThread(thread, new ICCreateThreadCallback()
{
  @Override
    public void onCreateThreadComplete(final ICThread icThread, final ICException e)
    {
      if (e == null)
        {
          //Success
        }
        else
        {
          //Failure
            e.printStackTrace();
        }
    }
});

e. Publishing messages

The SDK represents message data with the ICMessage class, new messages can be published easily by instantiating a ICMessage and invoking the publishMessage method. As mentioned in Creating threads, messaging in imiconnect is thread based so a message must be associated with an ICThread object. Obtain a ICThread object by calling the createThread method or, when replying to existing conversations, from an existing ICMessage instance.

ICMessage message = new ICMessage();

message.setMessage("Test message");
message.setThread(yourThreadObj);

ICMessaging.getInstance().publishMessage(message, new ICPublishMessageCallback()
{
    @Override
    public void onPublishMessageComplete(final ICMessage message, final ICException exception)
    {
        if (exception != null)
        {
            Log.e("PublishMessage", exception.toString());
        }
        else
        {
            Log.d("PublishMessage", "Published Successfully");
        }
    }
});

f. Closing the connection

The SDK 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 SDK from re-establishing the connection, you may call the disconnect method.

ICMessaging messaging = ICMessaging.getInstance();
 
try 
{  
    messaging.disconnect();
} 
catch (ICException e) 
{
    Log.e("Disconnect", e.toString());
}