Android
Configuration guide for the Recurly Engage Android SDK, enabling native prompt display and usage tracking in your mobile and TV apps.
Overview
The Recurly Engage Android SDK provides support for Android phones, tablets, TVs, Fire Tablets, and Fire TV. The SDK automatically handles display of modals (popups, video popups, and banners) and related user-triggered events. Inline prompts are accessible via helper functions with the necessary metadata for rendering within chosen areas of the app.
Key benefits
- SDK integration: Seamlessly embed prompts and track events across Android form factors.
- Automatic UI handling: Built-in support for modals, banners, and inline prompts without manual UI code.
- Broad device support: One SDK for phones, tablets, and TV devices.
Key details
The Recurly Engage Android SDK brings the ability to monitor consumption and show configured prompts within your native Android apps.
Install the SDK
The Engage Android SDK includes support for mobile, tablet and TV devices. The latest SDK version as well as the source code of an example app is available here. Please reach out to your customer success manager if you would like the keys needed to run the example app.
There are two options with installing the SDK: Add a dependency to an existing Gradle/Maven config, or add the local SDK packages.
Gradle/Maven Config
Gradle
// settings.gradle
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
// dependency
dependencies {
// amazon devices with inapp billing support
"amazonImplementation"("com.github.redfast.redfast-sdk-android-build:redfast-sdk-amazon:v2.3.0")
// google devices with inapp billing support
"googleImplementation"("com.github.redfast.redfast-sdk-android-build:redfast-sdk-google:v2.3.0"
// google devices without inapp billing support
"noiapImplementation"("com.github.redfast.redfast-sdk-android-build:redfast-sdk-noiap:v2.3.0")
// google devices without inapp and push support
"coreImplementation"("com.github.redfast.redfast-sdk-android-build:redfast-sdk-core:v2.3.0")
}
Maven
// Maven pom.xml
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
// dependency
<dependency>
<groupId>com.github.redfast.redfast-sdk-android-build</groupId>
<artifactId>redfast-sdk-google</artifactId> // or redfast-sdk-amazon, redfast-sdk-noiap, redfast-sdk-core
<version>v2.3.0</version>
</dependency>
Local package
Steps:
- Download the latest .aar files from here
- Create folder “libs” under “src/main”
- Add .aar libraries to “libs” folder
- Add library as a dependency in “build.gradle”. Example:
"implementation"(files("src/main/libs/redfast-google-release.aar"))
"implementation"(files("src/main/libs/redfast-amazon-release.aar"))
- For the
google-sdk.aar
library, it is also required to add the Android billing library dependency. Example:
"implementation"("com.android.billingclient:billing:6.0.1")
"implementation"("com.android.billingclient:billing-ktx:6.0.1")
- Enable the following features in
build.gradle
:
buildFeatures {
viewBinding = true
dataBinding = true
}
Initialize Engage
In the your app's main activity or application file, add the following line and replace with your appID and the userID of the current user. The appID is available on the Settings > Application screen within Pulse.
PromotionManager.initPromotion([appID], [userID])
Trigger popup via screen name
Allow the Engage SDK to display a popup on a specific Screen Name. Add the following line in the activity or fragment's onCreate function:
override fun onCreateView(
inflater: LayoutInflater,
container: ViewGroup?,
savedInstanceState: Bundle?
): View {
...
PromotionManager.setScreenName(binding.root, "ViewController") {
when (it.code) {
PromotionResult.timerExpired,
PromotionResult.declined,
PromotionResult.abort,
PromotionResult.accepted...
}
}
}
Trigger popup via button click
Allow the Recurly Engage SDK to display a popup configured with a Screen Name and Click ID. Add the following line in the button's click handler:
PromotionManager.getTriggerablePrompts(screenName = "home", clickId = "clickId", type = PathType.MODAL) {
val item = it.asList().firstOrNull()
item?.let { prompt ->
PromotionManager.showModal(promptId = prompt.id, requireContext()) {
Log.d("HomeFragment", "${it.code}")
}
}
}
Retrieve inline prompts
The SDK provides a function to retrieve a collection of inline items that are configured to trigger based on a Screen Name and/or Click ID. The properties of each Prompt object may be used to render the inline prompt in the appropriate location.
PromotionManager.getTriggerablePrompts("ScreenName", "ClickId") { prompts ->
prompts.firstOrNull()?.let {
/* Inline Prompt Image - based on device settings, one of:
rf_settings_bg_image_android_os_fire_tv_composite
rf_settings_bg_image_android_os_tablet_composite
rf_settings_bg_image_android_os_phone_composite
*/
val bgImage = it.bgImage
// Device Metadata - rf_metadata
val deviceMeta = it.deviceMeta
// Deeplink - rf_settings_deeplink
val deeplink = it.deeplink
// Confirm Button Color - rf_retention_confirm_button_text_color
val button1Color = it.button1Color
// Second Button Color - rf_retention_confirm_button_2_text_color
val button2Color = it.button2Color
// Cancel Button Color - rf_retention_cancel_button_text_color
val button3Color = it.button3Color
// All of the properties related to Timer
// rf_settings_close_seconds
val timerSeconds = it.timerSeconds
// rf_settings_close_seconds
val timerText = it.timerText
// rf_settings_timer_font_size
val timerTextFontSize = it.timerTextFontSize
// rf_settings_timer_font_color
val timerTextFontColor = it.timerTextFontColor
// All of the properties
val properties = it.properties
// Following methods will report the interaction to Redfast:
// Invoke when inline prompt is shown to user
it.impression()
// Invoke when user dismisses prompt
it.dismiss()
// Invoke when user declines prompt (Button 3)
it.decline()
// Invoke when timerSeconds expire and prompt is dismissed
it.timeout()
// Invoke if the "holdout" property is "true". This is normally automatically invoked.
it.holdout()
// Invoke when Button 1 is pressed
it.click()
// Invoke when Button 2 is pressed
it.click2()
}
}
Deep link to a media asset
You can insert deeplink key-value pairs in Pulse. When the user invokes the CTA, you can utilize these key-value pairs to send the user to a specific media asset within the app.
The deeplink value is saved in the completion callback from your setScreenName
, buttonClick
, and getInlines
Access custom metadata
Custom key-value pairs can be added to an item via Pulse. These values may be used to perform an action that is not the typical media asset deep link, like sending the user to a registration screen.
The meta data json is saved in the completion callback from your setScreenName
, buttonClick
, and getInlines
Send usage tracking event
Use this to send custom events using the SDK. If configured as a tracker within Pulse, these custom events can be used to target prompts at specific sets of users.
PromotionManager.customTrack("[customTrackId]")
Set UserId
You may change the userid after the SDK has been initialized, for example, when the user authenticates mid session. Note that it may take several seconds for the user's prompts to refresh.
PromotionManager.setUserId("[New userID]")
Debug view
The SDK provides a debug view modal, in which you can use the onscreen keyboard to either reset the current user or set a new user id.
To trigger the debug view for a specific screen, you can call the PromotionManager.showDebugView
function.
External libraries
Common
com.squareup.moshi:moshi-kotlin:1.9.2
com.squareup.moshi:moshi-kotlin-codegen:1.9.2
com.squareup.retrofit2:retrofit:2.6.2
com.squareup.retrofit2:converter-moshi:2.6.2
com.squareup.okhttp3:okhttp:4.2.2
com.squareup.okhttp3:logging-interceptor:4.2.2
org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.1
org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.1
com.github.bumptech.glide:glide:4.16.0
com.google.code.gson:gson:2.8.9
Conditional
Google IAP:
com.android.billingclient:billing:6.0.1
com.android.billingclient:billing-ktx:6.0.1
Amazon IAP:
amazon/in-app-purchasing-2.0.76.jar
Updated 2 days ago