Build a Core SDK App for Android

The Core SDK allows you to call all the necessary In-App Messaging APIs directly from your app. With the Core SDK, you’re in full control over the entire user experience—you tell the API when to send a message and the API tells you when a message is received.

This article applies to the following implementations:

If you want to use our ready-made user interface and user experience, use the UI SDK instead.

Create a CoreConfiguration object using the config file that you previously downloaded from your org, or you can manually add the values from within this config file.

Once you’ve added the config.json file to your project, you can reference it from the code.

1val config = CoreConfiguration.fromFile(myContext,"configFile.json")

1{
2  "OrganizationId": "00ZZZ0000000Zzz",
3  "DeveloperName": "MyMessagingForInAppDeployment",
4  "Url": "https://zzzz.my.api.url.salesforce-scrt.com"
5}

If you don’t want to use the config.json file in your project, you can configure the SDK manually using the Service API URL, the org ID, and the API name for the deployment.

1val url = URL("URL_TO_MY_SERVICE_API")
2val config = CoreConfiguration(url, "ORG_ID", "API_NAME_OF_DEPLOYMENT")

Get the CoreClient from the CoreClientFactory using the configuration object.

1​​val coreClient = CoreClient.Factory.create(myContext, config)

Start the core instance using the correct scope. To learn more about scopes, see Coroutines and Kotlin flows in the Android documentation.

1// Example of some coroutine code to get the scope.
2// See Android documentation for more info.
3private val supervisorJob = SupervisorJob()
4private val scope = CoroutineScope(Dispatchers.Main + supervisorJob)
5
6// Start listening for events using the correct scope
7coreClient.start(scope)

Create a ConversationClient from the CoreClient object.

1val uuid = UUID.randomUUID()
2val conversationClient = coreClient.conversationClient(uuid)

In order to get the pre-chat fields before a conversation, call the retrieveRemoteConfiguration method from your CoreClient object. The returned remote configuration object contains a form with an array of fields. Each pre-chat field has the properties necessary for you to build your pre-chat form. After you present the pre-chat form to the user, fill in the userInput field for each pre-chat field object. Then submit the pre-chat fields from the submitRemoteConfiguration method on the ConversationClient object.

1// Get the remote config object, which contains the pre-chat form
2val remoteConfig = coreClient.retrieveRemoteConfiguration()
3
4(remoteConfig as? Result.Success)?.data?.forms?.get(0)?.let { form ->
5  val field = form.formFields[0]
6
7  // Use the PreChatField attributes to render the form in your UI
8  val label = field.labels.display
9  val type: PreChatFieldType = field.type
10  // ...
11  val isRequired: Boolean = field.required
12
13  // Set the userInput value to what the end user entered in your form
14  field.userInput = "Sample User Input"
15
16  // Validate user input
17  if (field.validate() != PreChatErrorType.None) {
18    // Display error to end user
19  } else {
20    // Pass the completed form to the conversation client
21    val conversationClient = coreClient.conversationClient(uuid)
22    conversationClient.submitRemoteConfiguration(form.formFields)
23
24    // Start new conversation to submit the prechat form
25    conversationClient.sendMessage("Hello, I submitted my form and need some assistance…")
26  }
27}

To learn about hidden pre-chat fields, see Hidden Pre-Chat for Android.

Send a message with the sendMessage method on the ConversationClient object.

1conversationClient.sendMessage("It worked!")

You can listen for conversation activity with the ConversationClient object and by using Android’s Paging library. To learn about paged data, see Load and display paged data in the Android documentation.

For example, to listen for conversation entries, use the conversationEntriesPaged method.

1val conversationEntries =
2    conversationClient.conversationEntriesPaged()
3        .filterIsInstance<Result.Success<PagingData<ConversationEntry>>>().map {
4            it.data
5        }

Use your PagingDataAdapter class to listen to the latest events.

1conversationEntries.collectLatest {
2    myPagingAdapter.submitData(it)
3}

Your ViewHolder class can extract information from the conversation entry.

1// Extract the text from a conversation entry
2private fun getText(item: ConversationEntry?): String =
3    when (val payload = item?.payload) {
4    is EntryPayload.MessagePayload ->
5
6        when (val content = payload.abstractMessage.content) {
7        is StaticContentFormat.TextFormat -> content.text
8
9            // Handle other message formats (e.g. QuickRepliesFormat, RichLinkFormat)
10            else -> content.formatType.toString()
11        }
12
13    // Handle other entry types (e.g. ParticipantChangedPayload, AcknowledgeReadPayload)
14    else -> payload?.entryType.toString()
15}

To listen for transient events that come from the network, such as typing indicator feedback and network connectivity info, use Kotlin flows on ConversationClient and CoreClient.

To monitor conversation events on the ConversationClient instance, use the following properties:

• conversation: To observe the current conversation.
• events: To listen for events specific to this conversation.

To monitor general events on the CoreClient instance, use the following properties:

• networkConnectivityState: To determine the network state.
• events: To listen for general events (including events from all conversations).

For example, to listen for typing events in a particular conversation, filter on the events property.

1// Listen for progress/typing indicator events
2val events =
3    conversationClient.events.filterIsInstance<ConversationEvent.ProgressIndicator>()

When you receive events, you can extract information from the contents and pass it to the UI.

1events.collectLatest {
2    // Grab the status text of the event
3    val text = "Typing Event: ${it. conversationEntry.entryType}"
4
5    // Display the text
6    Toast.makeText(requireContext(), text, Toast.LENGTH_SHORT).show()
7}

The Participant interface has a role field of type string that maps to a participant role type. Participant maps to the sender field of the ConversationEntry object.

You can enhance your users’ experience by adding push notifications, passing information to Salesforce about a verified user, sending hidden pre-chat fields, adjusting chat button visibility based on business hours, and more.

For enhanced features, see Enhance the Experience for Android.

For more details about the Core SDK, see the Android Reference Documentation.

j

Get Started

iOS Guidelines

Android Guidelines

Requirements

Install the SDK

Build a UI SDK App

Build a Core SDK App

Manage Conversations

Customize the UI

Bring Your Own UI

Enhance the Experience

Sample Apps

Enhanced Chat API Developer Guide