MCA SDK Getting Started Guide

What is the MCA SDK?

The Mobile Cashback Alerts SDK offers a simple way to notify users when they visit eligible 

websites and provides a single-tap activation that allows users to earn from their purchases. The MCA SDK uses all the same Wildfire Systems merchant relationships and data to pop a heads-up notification and display the commission amount that a user is likely to earn from a given merchant.



Recent Changes

  • - Resolved crashing bug related to storing very large merchant domain lists. 
  • - Updated requestSecurityDialog() method to take a callback in response to request for back stack handling
    • Automatically bring the user back to host app upon granting Accessibility permission so they don't need to find their way back to the host app
    • Breaking Change: Fixed misspelling of isAccessiblilityEnabled method
    • Breaking Change: Use non-vanity URLs for default activation links (which implies "&tc=" instead of "?tc=")
  • - Use an alternate URL in the notification (this also deprecates the addParamsToVanity method); Hide the Share+Earn action

  • - Improved passing previously created Device object

  • - TC parameter support

  • - Customizable Accessibility screen strings


  • Minimum Android API level 21 (Lollipop 5.0)

  • Chrome for Android (webviews and other browsers are incompatible at this time)

Getting Started

Note that the following screenshots are from the Bumblebee 2021.1.1 Patch 3 version of Android Studio.  Some features in Android Studio may be located in different places.

Setting Up Your Application

Create a new application as you normally would (in this example, we'll select an empty activity):

Screen Shot 2022-06-22 at 11.37.12 AM
Screen Shot 2022-06-22 at 11.40.31 AM

Add the JitPack repository to your settings.gradle project:

repositories {
maven { url '' }
Screen Shot 2022-06-22 at 11.42.08 AM

Select "Sync Now" and allow the dependency map to update.

Then, add the MCA SDK dependency to your build.gradle module:

implementation 'com.github.wildlink:android-mobile-cash-back-alert:'
Screen Shot 2022-06-22 at 11.44.23 AM

Select "Sync Now" again and allow the dependency map to update.

Main Application Code

The MCA SDK shows notifications to your users when they visit a website in Chrome that's eligible for earning (either in the form of Share & Earn or Cashback). In order for the SDK to perform this task, it requires the Accessibility permission. Unlike other permission requests where a permission prompt happens inside the context of the host app, for the Accessibility permission the user must go to a settings page in Android's Settings and toggle the permission to “ON.”

As a convenience, the MCA SDK provides a method to check if the Accessibility permission has been granted and another method to take the user to the Accessibility settings screen. However, the user must still tap into your application from this list view and then toggle the permission to “ON.”

The host app will be responsible for guiding the user through this process, setting their expectations about why this permission is necessary and valuable for them. For our demo application, we'll provide a simple button in the MainActivity that will take the user to the Accessibility screen (exercising the method provided by MCA SDK).

Let's first add a button to our view. In activity_main.xml replace the TextView element and add the following Button element:

android:text="Hello World!"
app:layout_constraintTop_toTopOf="parent" />

android:text="Grant Accessibility"
app:layout_constraintVertical_bias="0.496" />
Screen Shot 2022-06-22 at 11.52.05 AM

Note: The toggle between the code view and design view has changed in recent versions of Android Studio (from the tabs near the bottom left of the code window to the icons at the top right in newer versions).  This screenshot uses the "Code" view.

Next, we'll add the following code to the MainActivity.kt to connect the button to the MCA SDK's methods:

package com.example.cashbackdemo

import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.content.IntentFilter
import android.os.Bundle
import android.util.Log
import android.view.View
import android.widget.Button
import android.widget.Toast
import androidx.localbroadcastmanager.content.LocalBroadcastManager
import me.wildfire.mobilecashbackalert.*
import me.wildfire.mobilecashbackalert.models.CbDevice

class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {

var button = findViewById<Button>(
button.setOnClickListener(View.OnClickListener {
if (!MobileCashbackAlert.isAccessibilityEnabled(this)){
                MobileCashbackAlert.requestSecurityDialog(this) {
                    val intent = Intent(this,
                    intent.flags =
                        Intent.FLAG_ACTIVITY_CLEAR_TASK or Intent.FLAG_ACTIVITY_NEW_TASK
                    intent.action = Intent.ACTION_MAIN
           } else {
Toast.makeText(this, "Cashback enabled", Toast.LENGTH_LONG).show()

Note: Your "package" line at the beginning of the file should reflect your project (i.e. if you chose a different project name).

Also Note: You may notice that the imported library is showing an unresolved reference error (even though the import is valid as we added it to our gradle imports).  In some cases, the caching of external dependencies needs to be refreshed.  There are a few ways to do this, but the easiest way is often to use the File -> Invalidate Caches feature.  Selecting Invalidate and Restart usually resolves this issue.

The onActivityResult is invoked when the Accessibility permission setting is changed and when the user returns to the activity. However, the user does not need to return to the activity in order for the background service to begin running, so the user will begin receiving notifications right away upon visiting eligible sites.

Next, we'll configure the application apart from the UI thread to initialize the SDK with our application's credentials and we'll set our split with the user. Create a new Kotlin class by right-clicking on your application from the left panel in Android Studio. We'll call this new class MyApplication.

Now add the following code to this new class:

import me.wildfire.mobilecashbackalert.*

class MyApplication : Application() {
companion object {
lateinit var clientInfo: ClientInfo
override fun onCreate() {
var notificationData = NotificationData()
clientInfo = ClientInfo("Client ID Goes Here",
clientSecret = "Client Secret Goes Here",
notificationData = notificationData,
userSplit = 0.5) // fifty percent

Note: Be sure to replace the placeholders with your actual Application's client ID and secret (contact your Wildfire Systems account manager if you need these values).

Note: We have used a 50/50 split in this example. We assume that you may want to take a portion of the user's earnings as part of your business model. If you wanted to pass the entire earnings along to the user then you would set this value to 1. If you wanted to take 75% of the user's earnings you would set this value to 0.25, and so on. This split is just between you and your user. The split agreement you have with Wildfire Systems is already accounted for before this split is applied.

Screen Shot 2022-06-22 at 12.20.42 PM

Finally, before we run our application, we have to tell Android about our application class so that it knows how to reference it. In your AndroidManifest.xml add the following attribute to the application tag:

Screen Shot 2022-06-22 at 12.21.22 PM

Note: Depending on your configuration, you may have build errors if you attempt to run your project at this point.  If you encounter this, check to ensure you're using JDK 11 and not JDK 1.8 for your Gradle configuration.  Under Android Studio > Preferences you'll find a section under Build, Execution, Deployment > Build Tools > Gradle where you may need to change from v1.8 to v11.

Screen Shot 2022-06-22 at 12.22.35 PM

You should now be able to:

  • Run your application

  • Select the button and be taken to the Accessibility screen

  • Grant permission (toggle Accessibility on)

  • Begin browsing in Chrome and receiving notifications for eligible web sites

The notifications contain two actions: Share & Earn which will invoke the native sharing dialog and populate it with a vanity URL (i.e. and Activate Cashback, which will reload the user's current web page with cash-bask earning enabled.


If at this point you're able to run your project but you don't see notifications popping when you switch to an eligible website in Chrome (i.e.,, ensure that your client ID and secret are correct.  If these values are incorrect then the SDK will fail to fetch the eligible merchant domain list and it will not match any websites.  You can verify that this is the issue by filtering Logcat for "auth" and see if there are error messages like:

errorMessage={"ErrorMessage":"Auth Signature Mismatch: App Auth did not match...

Next Steps and Further Information

This is a simple example of how a host application can leverage the MCA SDK in order to give your users the ability to earn from their own purchases and the purchases of others. Because this system only works with the Accessibility permission granted, it's important to ensure that your users know why they should allow this permission and how to grant it. Amazon Assistant is a popular Android app that does a good job of describing this value proposition and shows the current status of the permission to the user.

The MCA SDK currently fires a notification anytime the user visits an eligible website and does not fire again until they change domains. For example, multiple pages viewed on will only fire a single notification (the first page view). Visiting and then another site and the again will fire the notification again. There is currently no further limiting of notifications.

Getting the Device ID from the SDK instance

Wildfire Systems performs all attribution to a Device ID. This is not tied to a hard device identifier like a serial number but rather it represents a generic client instance. As such, it does not persist across reinstalls on the same device. In order for your host app to carry through the attribution to your users, you'll need to take the generated Device ID and associate it to your user (i.e. in your backend data store). When the user grants the Accessibility permission, the MCA SDK broadcasts an event that can be caught with a broadcast receiver. Let's look at an example for how this works. Add the following code to your onCreate function in your MainActivity.kt:

// Define the broadcast receiver method
val deviceRegistrationListener = object: BroadcastReceiver(){
override fun onReceive(context: Context?, intent: Intent?) {
Log.d("foo", "deviceRegistrationListener - onReceive called")
intent?.let {
when (intent.action) {
val device = it.getParcelableExtra<CbDevice>(Constants.KEY_DEVICE)
Log.d("foo", "device id = " + device?.deviceId)
else -> {

// Register the broadcast receiver
Screen Shot 2022-06-22 at 12.36.49 PM

This code defines a broadcast receiver (and registers it) that will be invoked when the user grants the Accessibility permission (even if they never return to your activity). This event will be fired after the device has been created in Wildfire Systems's backend and returned to the client, so you can safely retrieve the device.deviceId and then make a web request to store it in your backend.

Pausing and Resuming the Service

After we've received the Accessibility permission to run the URL matching service, the user may want to turn off the service from your host app for a time and resume it later. We want to avoid making the user go back into their settings, so we offer methods to pause and resume the service. When paused, the Accessibility permission is still enabled, but there's no evaluation of the user's URLs they visit, so they will not receive any notifications. Another UX option is to offer the user a single button to “pause notifications for 1 hour” where the host app could pause the service and start a timer to enable the service in an hour.

// to pause URL evaluation and notifications:
// to resume URL evaluation and notifications:

Customizing Notification Content

The following figure illustrates the customizable items:

If you would like to customize the notification messages to apply your own branding and messages, you may do so by overriding the default values like this in the MyApplication class:

var notificationData = NotificationData()
notificationData.titleText = "Earn on your {merchantName} purchases"
notificationData.largeViewLine1Text = "Or share and earn up to " + maxCommissionRate + "!!"
Screen Shot 2022-06-22 at 12.38.27 PM

You can use the following variables either inline as curly braced tokens or as variables:

  • merchantName (i.e., Walmart)

  • maxCommissionRate (i.e., 2% or $2.50)

  • defaultCommissionRate (this is “the most likely earning rate” based on broadest product coverage vs. max which is the highest payout rate)

In addition to changing the default notification text, you can also change other properties, including the small and large icons of the notification. Here's a full list of the configurable properties:

Customizing Accessibility Setting Strings

When the user goes to the system settings to grant the Accessibility permission, there is an opportunity to describe the permission with a name and a description property. To do this, simply create values in your strings.xml to override the defaults:

<string name="app_name">Cashback Demo</string>
<string name="cb_service_name">service name goes here</string>
<string name="cb_service_desc">service description goes here</string>
Screen Shot 2022-06-22 at 12.39.17 PM

Example of how these strings display:

Adding a TC Parameter to Generated Links

As of v1.0.0.8 the host app can inject a TC (custom Tracking Code) parameter. This value can be used for passing an encoded user ID, a shopping trip ID or any other reference that the host app wants to pass through. Which will be returned as part of the commission record to help add more detailed attribution to the commission.

To set a TC parameter, the host app can invoke the following method from the MainActivity:

MobileCashbackAlert.eligibleMerchant(object: EligibleMerchantCallback {
override fun onData(concept: Concept, destinationUrls: MutableDestinationUrls) {
val newUrl = "${destinationUrls.activateUrl}&tc=abc123"
Log.d("foo", "newURL is $newUrl")
destinationUrls.activateUrl = newUrl

Screen Shot 2022-06-22 at 12.39.59 PM

Passing a TC parameter in this way will result in a sharable vanity URL like the following:

When an eligible purchase is completed using this link, the value abc123 will be returned as part of the commission record sent to your chosen callback URL.

Using the MCA SDK with a previously generated device

As of v1.0.0.9 the MCA SDK allows you to pass in a Device object. If your app has already generated a Wildfire Device ID (i.e., if you're using the Wildfire API Wrapper), then you should pass in this device to the MCA SDK so that a new device is not created. You may pass this reference in like so:


The Device method allows you to pass in your previous generated and stored JSON for the device. When the MCA SDK receives a device in this way, it will not generate a new device when the MobileCashbackAlert.init() method is called.

Hiding the Share+Earn action

We recommend always giving users the option to share an affiliate link or activate cashback to maximize earning opportunities, but we also understand that sometimes a partner only wants to show a single appeal to their users. As of v1.0.0.11 the MCA SDK allows the host app to set a flag to hide the Share+Earn action from eligible merchant notifications. In the notificationData, set the disableShare property to true.

notificationData.disableShare = true

Now, when the notification fires, only the Activate Cashback action is shown to the user.

Replace URL in notification

Occasionally, a partner wants to send a click through to their server before they send it along to Wildfire Systems. To support this, in v1.0.0.11 of the MCA SDK, there's a new method available to intercept the eligible merchant notification before it's sent and change the default URL. Take the following example code in the MainActivity.kt:

// Intercept eligible merchant event and change URL before the notification fires
MobileCashbackAlert.eligibleMerchant(object:EligibleMerchantCallback {
override fun onData(concept: Concept, destinationUrls: MutableDestinationUrls) {
Log.d("foo", "Callback to eligibleMerchant with " + concept.toString())
destinationUrls.activateUrl = "https://mynewurl?domain=${concept.Domain}&merchantId=${concept.Merchant.ID}&originalUrl=" + destinationUrls.activateUrl
destinationUrls.shareUrl = "https://mynewurl?originalUrl=" + destinationUrls.shareUrl

A few things to note in this example:

  • The activateUrl and shareUrl values can be set independently if a different value needs to be passed to each action.

  • The concept object contains several relevant data points that describe the eligible merchant (the concept.toString() will show these values in logcat, so you can get a sense for what's available).

  • This method is blocking the notification from firing, so it's important to avoid making network requests to generate these replacement URLs if possible, as they may take time to complete (or may not complete at all).

Known Issues

  • Motorola: Notifications don't show on Motorola devices due to inconsistencies in reporting of on-screen content. Motorola market share is about 3% of global Android devices.

  • Oppo: Notifications don't show on some Oppo devices (notifications are non-standard). Oppo market share is between 5-7% of global Android devices.