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.

 

mcagif

Recent Changes

  • Jul 22, 2020 - Use an alternate URL in the notification; Hide the Share+Earn action

  • May 4, 2020 - Improved passing previously created Device object (available in 1.0.0.9)

  • Apr 22, 2020 - TC parameter support (available in 1.0.0.8)

  • Mar 17, 2020 - Customizable Accessibility screen strings (available in 1.0.0.7)

Pre-requisites

  • Minimum Android API level 21 (Lollipop 5.0)

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

Getting Started

Setting Up Your Application

Create a new application as you normally would (select an empty activity):

 

Add the JitPack repository to your settings.gradle project:

repositories {
google()
mavenCentral()
maven { url 'https://jitpack.io' }
}

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

implementation 'com.github.wildlink:android-mobile-cash-back-alert:1.0.0.12'
 
grade module

 

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 Cash-back). In order for the SDK to perform this task, it requires the Accessibility permission. Unlike other permission requests, the user must actually go to a settings page in Android 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 add the following element:

<Button
android:id="@+id/button"
android:layout_width="240dp"
android:layout_height="94dp"
android:text="Grant Accessibility"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintHorizontal_bias="0.497"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toBottomOf="@+id/textView"
app:layout_constraintVertical_bias="0.496" />
 

Note: In the example above, we assume that there is a TextView element with an ID of textView. 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).

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.Intent
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.util.Log
import android.view.View
import android.widget.Button
import android.widget.Toast
import me.wildfire.mobilecashbackalert.ClientInfo
import me.wildfire.mobilecashbackalert.MobileCashbackAlert
import me.wildfire.mobilecashbackalert.NotificationData

class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

var button = findViewById<Button>(R.id.button)
button.setOnClickListener(View.OnClickListener {
if (!MobileCashbackAlert.isAccessiblilityEnabled(this)){
MobileCashbackAlert.requestSecurityDialog(this, MobileCashbackAlert.RESULT_ACCESSIBILITY)
} else {
Toast.makeText(this, "Cashback enabled", Toast.LENGTH_LONG).show()
}
})
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
Log.d("foo","onActivityResult called with $requestCode, $resultCode")

if (requestCode == MobileCashbackAlert.RESULT_ACCESSIBILITY) {
if (MobileCashbackAlert.isAccessiblilityEnabled(this)) {
Toast.makeText(this, "Cashback enabled", Toast.LENGTH_LONG).show()
} else {
Toast.makeText(this,"This app will not work without accessibility enabled", Toast.LENGTH_LONG).show()
}
}
}
}

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 android.app.Application
import me.wildfire.mobilecashbackalert.ClientInfo
import me.wildfire.mobilecashbackalert.MobileCashbackAlert
import me.wildfire.mobilecashbackalert.NotificationData


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

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.

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:

android:name=".MyApplication"

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. https://wild.link/walmart/abc123) and Activate Cashback, which will reload the user's current web page with cash-bask earning enabled.

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 Walmart.com will only fire a single notification (the first page view). Visiting Walmart.com and then another site and the Walmart.com 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?) {
intent?.let {
when (intent.action) {
Constants.ACTION_DEVICE_CREATED -> {
val device = it.getParcelableExtra<CbDevice>(Constants.KEY_DEVICE)
Log.d("Foo", "device id = " + device.deviceId)
}
else -> {
}
}
}
}
}
 
// Register the broadcast receiver
LocalBroadcastManager.getInstance(this).registerReceiver(deviceRegistrationListener,
IntentFilter(Constants.ACTION_DEVICE_CREATED)
)

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:
MobileCashbackAlert.disableUrlProcessing()
 
// to resume URL evaluation and notifications:
MobileCashbackAlert.enableUrlProcessing()

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 + "!!"

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:

<resources>
<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>
</resources>
 

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.addParamsToVanity(object: Callback {
override fun getParams(type: MobileCashbackAlert.Type, concept: Concept): HashMap<String, String> {
val map = HashMap<String, String>()
map.put("tc","foo123")
return map
}
})

Passing a TC parameter in this way will result in a sharable vanity URL like the following: https://wild.link/walmart/abc123?tc=foo123

When an eligible purchase is completed using this link, the value foo123 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:

MobileCashbackAlert.setDevice(Device(wildfireDeviceJson))

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.