Implement In-App Messaging on Android

To use certain in-app messaging features, such as button actions, you must change some SDK configurations.

Required Methods for Button Actions

Marketers can configure the action that occurs when an end user taps a button on an in-app message. The SDK handles actions for Notification Settings and Location Settings, while actions for Web URL and App URL require that you implement UrlHandler as a new SDK initialization method.

The following example shows how you can configure the SDK to handle button clicks in in-app messages.

1SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
2  inAppMessagingFeatureModuleConfig = InAppMessagingFeatureConfig.builder().apply {
3    // Other configuration options
4    // Tell the SDK how to handle button clicks in an In-App Message
5    setUrlHandler { context, url, _ ->
6      getActivity(
7        context,
8        Random().nextInt(),
9        Intent(Intent.ACTION_VIEW, url.toUri()),
10        PendingIntent.FLAG_UPDATE_CURRENT
11      )
12    }
13  }.build()
14}) {
15  // TODO handle initialization status
16}

If your app uses version 10 of the SDK, use this code.

1SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
2    engagementModuleConfig = MarketingCloudConfig.builder().apply {
3        // Other configuration options
4        // Tell the SDK how to handle button clicks in an In-App Message
5        setUrlHandler(UrlHandler { context, url, _ ->
6            PendingIntent.getActivity(
7                context,
8                Random().nextInt(),
9                Intent(Intent.ACTION_VIEW, url.toUri()),
10                PendingIntent.FLAG_UPDATE_CURRENT
11            )
12        })
13    }.build(applicationContext)
14}) {
15    // TODO handle initialization status
16}

If your app uses version 8 of the SDK, use this code.

1SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
2  pushModuleConfig = MarketingCloudConfig.builder().apply {
3    setApplicationId("{mc_application_id}")
4    setAccessToken("{mc_access_token}")
5    setSenderId("{fcm_sender_id}")
6    setMarketingCloudServerUrl("{marketing_cloud_url}")
7    setMid("{mid}")
8    setNotificationCustomizationOptions("{your instance of NotificationCustomizationOptions}")
9
10    // Tell the SDK how to handle button clicks in an In-App Message
11    setUrlHandler(UrlHandler { context, url, _ ->
12      PendingIntent.getActivity(
13        context,
14        Random().nextInt(),
15        Intent(Intent.ACTION_VIEW, Uri.parse(url)),
16        PendingIntent.FLAG_UPDATE_CURRENT
17      )
18    })
19    // Other configuration options
20  }.build(applicationContext)
21}) {
22  // TODO handle initialization status
23}

If your app uses version 7 of the SDK, use this code.

1MarketingCloudSdk.init(applicationContext as Application, MarketingCloudConfig.builder().apply {
2  setApplicationId("{mc_application_id}")
3  setAccessToken("{mc_access_token}")
4  setSenderId("{fcm_sender_id}")
5  setMarketingCloudServerUrl("{marketing_cloud_url}")
6  setMid("{mid}")
7  setNotificationCustomizationOptions("{your instance of NotificationCustomizationOptions}")
8
9  // Tell the SDK how to handle button clicks in an In-App Message
10  setUrlHandler(UrlHandler { context, url, _ ->
11    PendingIntent.getActivity(
12      context,
13      Random().nextInt(),
14      Intent(Intent.ACTION_VIEW, Uri.parse(url)),
15      PendingIntent.FLAG_UPDATE_CURRENT
16    )
17  })
18
19  // Other configuration options
20
21}.build(applicationContext)) {
22  // TODO handle initialization status
23}

Optional Methods

To control aspects of message display and to get information about the in-app message display lifecycle, use the SDK’s optional in-app messaging EventListener

After the SDK’s initialization is complete, you can register your in-app message EventListener with InAppMessageManager.

1// Set at configuration time
2SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
3  inAppMessagingFeatureModuleConfig = InAppMessagingFeatureConfig.builder().apply {
4   setEventListener(object : InAppMessageManager.EventListener {
5     override fun shouldShowMessage(message: InAppMessage): Boolean {
6       return if (shouldShowMessage /* Your Custom logic confirming to show in-app message */) {
7         true
8       } else {
9         // Store message id for later
10         val blockedMessageId = message.id
11         false
12       }
13     }
14     override fun didShowMessage(message: InAppMessage) = Unit
15     override fun didCloseMessage(message: InAppMessage, action: InAppMessageCloseAction) = Unit
16   })
17  }.build()
18})
19
20// Or set at anytime after configuration
21InAppMessagingFeature.requestSdk { inAppMessagingFeatureModule ->
22  inAppMessagingFeatureModule.getInAppMessageManager().setInAppMessageListener(...)
23}

If your app uses version 10 of the SDK, use this code.

1MarketingCloudSdk.requestSdk { engagementSdk ->
2  engagementSdk.inAppMessageManager.setInAppMessageListener(object :
3      InAppMessageManager.EventListener {
4      override fun shouldShowMessage(message: InAppMessage): Boolean {
5          return if (shouldShowMessage /* Your Custom logic confirming to show in-app message */) {
6              true
7          } else {
8              // Store message id for later
9              val blockedMessageId = message.id
10              false
11          }
12      }
13      override fun didShowMessage(message: InAppMessage) = Unit
14      override fun didCloseMessage(message: InAppMessage) = Unit
15  })
16}

If your app uses version 8 of the SDK, use this code.

1SFMCSdk.requestSdk { sdk ->
2  sdk.mp {
3    it.inAppMessageManager.setInAppMessageListener(object : InAppMessageManager.EventListener {
4      override fun shouldShowMessage(message: InAppMessage): Boolean {
5        return if (shouldShowMessage /* Your Custom logic confirming to show in-app message */) {
6          true
7        } else {
8          // Store message id for later
9          val blockedMessageId = message.id
10          false
11        }
12      }
13      override fun didShowMessage(message: InAppMessage) = Unit
14      override fun didCloseMessage(message: InAppMessage) = Unit
15    })
16  }
17}

If your app uses version 7 of the SDK, use this code.

1MarketingCloudSdk.requestSdk { sdk ->
2  sdk.inAppMessageManager.setInAppMessageListener(object : InAppMessageManager.EventListener {
3
4    override fun shouldShowMessage(message: InAppMessage): Boolean {
5
6      return if (shouldShowMessage /* Your Custom logic confirming to show in-app message */) {
7        true
8      } else {
9        // Store message id for later
10        val blockedMessageId = message.id()
11        false
12      }
13    }
14
15    override fun didShowMessage(message: InAppMessage) = Unit
16    override fun didCloseMessage(message: InAppMessage) = Unit
17  })
18}

didShowMessage and didCloseMessage

The didShowMessage and didCloseMessage callback methods help ensure that you can appropriately manage your app’s view state. In-app messages are shown in an activity controlled by the SDK within your app’s activity stack. Your app is required to respond to a view appearing or disappearing.

didShowMessage is invoked when the in-app message is initially presented.
didCloseMessage is invoked after the user closes the message and includes the close reason.

Prevent or Delay Message Display

You can delay or prevent an in-app message’s display. For example, you can choose to prevent an in-app message from displaying during the loading process, sign-in flow, and other situations. To prevent or delay message display, set the shouldShowMessage method to return false.

Furthermore, you can capture data of any in-app message and use it for displaying the specific message at a later time. For example, you can present the message after an end user has successfully signed in by capturing the ID of the message and showing that message later, as shown in this example.

1InAppMessagingFeature.requestSdk { inAppMessagingFeatureModule ->
2  inAppMessagingFeatureModule.getInAppMessageManager().showMessage(blockedMessageInd)
3}

If your app uses version 10 of the SDK, use this code.

1MarketingCloudSdk.requestSdk { engagementSdk ->
2  engagementSdk.inAppMessageManager.showMessage(blockedMessageId)
3}

If your app uses version 8 of the SDK, use this code.

1SFMCSdk.requestSdk { sdk ->
2  sdk.mp {
3    it.inAppMessageManager.showMessage(blockedMessageId)
4  }
5}

If your app uses version 7 of the SDK, use this code.

1MarketingCloudSdk.requestSdk { sdk->
2  sdk.inAppMessageManager.showMessage(blockedMessageId)
3}

Customize Display

By default, in-app messages use your device’s system font. However, you can override the default font face to customize the appearance of an in-app message’s title, body, and button labels.

You can’t alter the font size since the message’s design defines it.

Note

To set the display font, pass the SDK a valid TypeFace for the device’s installed fonts, or your app’s custom fonts as shown in this example.

1// set at configuration time
2SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
3  inAppMessagingFeatureModuleConfig = InAppMessagingFeatureConfig.builder().apply {
4    setTypeface(appFontFace)
5  }.build()
6})
7
8// OR set after configuration time
9InAppMessagingFeature.requestSdk { inAppMessagingFeatureModule ->
10  inAppMessagingFeatureModule.getInAppMessageManager().setTypeface(appFontFace)
11}

If your app uses version 10 of the SDK, use this code.

1MarketingCloudSdk.requestSdk { engagementSdk ->
2  engagementSdk.inAppMessageManager.setTypeface(appFontFace)
3}

If your app uses version 8 of the SDK, use this code.

1SFMCSdk.requestSdk { sdk ->
2  sdk.mp {
3    it.inAppMessageManager.setTypeface(appFontFace)
4  }
5}

If your app uses version 7 of the SDK, use this code.

1MarketingCloudSdk.requestSdk { sdk->
2  sdk.inAppMessageManager.setTypeface(appFontFace)
3}

Set Status Bar Color

The SDK doesn’t use AppCompatActivity and can’t inherit your app’s status bar color automatically. Instead, you must define a custom status bar color. The SDK applies this color on Android API versions that support the status bar color, which is Lollipop and newer.

1// set at configuration time
2SFMCSdk.configure(applicationContext as Application, SFMCSdkModuleConfig.build {
3  inAppMessagingFeatureModuleConfig = InAppMessagingFeatureConfig.builder().apply {
4   setStatusBarColor(
5      ContextCompat.getColor(this as Context, R.color.colorPrimary)
6    )
7  }.build()
8})
9
10// OR set after configuration time
11InAppMessagingFeature.requestSdk { inAppMessagingFeatureModule ->
12  inAppMessagingFeatureModule.getInAppMessageManager().setStatusBarColor(
13    ContextCompat.getColor(this as Context, R.color.colorPrimary)
14  )
15}

If your app uses version 10 of the SDK, use this code.

1MarketingCloudSdk.requestSdk { engagementSdk ->
2  engagementSdk.inAppMessageManager.setStatusBarColor(
3    ContextCompat.getColor(this as Context, R.color.colorPrimary)
4  )
5}

If your app uses version 8 of the SDK, use this code.

1SFMCSdk.requestSdk { sdk ->
2  sdk.mp {
3    it.inAppMessageManager.setStatusBarColor(
4      ContextCompat.getColor(this as Context, R.color.colorPrimary)
5    )
6  }
7}

If your app uses version 7 of the SDK, use this code.

1MarketingCloudSdk.requestSdk { sdk->
2  sdk.inAppMessageManager.setStatusBarColor(
3    ContextCompat.getColor(this as Context, R.color.colorPrimary)
4  )
5}