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 Recurly Engage Android SDK is available on Maven Central. The SDK is split into variants depending on your target platform and billing setup — choose the one that fits your app:

Add via Gradle

Step 1 — Confirm mavenCentral() is included in your settings.gradle or settings.gradle.kts:

// settings.gradle.kts
dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    mavenCentral()
  }
}

Step 2 — Add the SDK dependency in your app's build.gradle.kts. Pick the variant that matches your setup:

// build.gradle.kts
dependencies {
  // Google Play with in-app billing
  implementation(“com.recurly:engage-sdk-android-google:2.3.5”)

  // Amazon Fire with in-app billing
  implementation(“com.recurly:engage-sdk-android-amazon:2.3.5”)

  // Google Play without in-app billing
  implementation(“com.recurly:engage-sdk-android-noiap:2.3.5”)

  // Google Play without in-app billing or push
  implementation(“com.recurly:engage-sdk-android-core:2.3.5”)
}

Step 3 — Sync your project with Gradle files.

Add via Maven

No additional repository configuration is needed — the SDK is published to Maven Central. Add the dependency to your pom.xml:

<dependency>
  <groupId>com.recurly</groupId>
  <!-- Replace artifactId with your chosen variant:
       engage-sdk-android-google | engage-sdk-android-amazon |
       engage-sdk-android-noiap  | engage-sdk-android-core   -->
  <artifactId>engage-sdk-android-google</artifactId>
  <version>2.3.5</version>
</dependency>

Add via local package

If you prefer to integrate the .aar files directly:

1. Download the latest .aar files from GitHub Releases
2. Create a libs folder under src/main
3. Copy the .aar files into that folder
4. Add them as dependencies in your build.gradle.kts:

implementation(files(“src/main/libs/redfast-google-release.aar”))

5. If using the Google IAP variant, also add the billing library:

implementation(“com.android.billingclient:billing:6.0.1”)
implementation(“com.android.billingclient:billing-ktx:6.0.1”)

6. Enable the following 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
          ...
        }
    }
}

// PromotionResult:
//   val code: PromotionResultCode,
//   val value: deeplink,
//   val meta: metadata

// PromotionResultCode:
//   timeout,
//   declined,
//   abort,
//   accepted,
//   notApplicable,
//   notSupported,
//   disabled,
//   holdout,
//   button1, // User clicked button 1 (primary button, used in both modal and inline)
//   button2, // User clicked button 2 (secondary button, modal only)
//   button3, // User clicked button 3 (tertiary button, modal only)
//   dismiss // User dismissed the modal/inline (available for both modal and inline)

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