Skip to main content


Step 1: Setup

  • Create an app and grab your API Token.
  • Add a test device with a test user identifier.


Add the following to the repositories closure of the app's module build.gradle file:

repositories {
maven { url "" }

Next, add the following to the module dependencies closure:

dependencies {
implementation 'com.tapr:tapresearch:2.5.+' // Replace with the latest version
implementation '' //Optional - See Below

Be sure to use the latest version of the SDK. You can find the latest version on the releases page

Android Play Services (Optional)

The SDK will try to collect the AdvertisementID from the device. The AdvertisementID is exposed from the Android Play Services. To enable the Android Play Services, add the following library to the module build.gradle file:

Step 2: Callbacks

Placement Callbacks

The PlacementEventListener will notify the app when a placement(s) is ready or not available.

public interface PlacementEventListener {
void placementReady(TRPlacement placement);

void placementUnavailable(String placementId);

A placementReady is fired when a placement has been received and is available to show.

A placementUnavailable is fired when a placement is not currently available.

An unavailable placement could become available later and at that time placementReady will be called.

Reward Callbacks

RewardListener rewardListener = new RewardListener() {
public void onDidReceiveReward(TRReward reward) {
String rewardText = String.format("You've earned %d %s for completing a survey.\n%s",
// Your reward logic
public void onResume() {

public void onPause() {

The SDK will check if the user has unredeemed rewards in the following events:

  • On SDK initialization
  • When the user exits TapResearch Survey Wall

The RewardListener and RewardCollectionListener listeners are interfaces for handling new rewards a player has earned during their session. The object that implements the interface should be passed to TapResearch.getInstance().setRewardListener to received single rewards at a time (Shown above). Use TapResearch.getInstance().setRewardCollectionListener to receive rewards as a collection.

It is important to note that onDidReceiveReward will be called back-to-back if the player completed multiple surveys in one session.

Step 3: Initialize


Our SDK requires you to have an application class. Create a new class and have it extend Application. Override the onCreate() method and call the TapResearch configure method.

public class MyApp extends Application {
public class onCreate() {
TapResearch.configure(YOUR_API_TOKEN, this, YOUR_EVENT_LISTENER);

Step 4: Set User Identifier

Be sure to set your unique user identifier, or test identifier.


Step 5: Handle Placements

A Placement is an object that should be attached to the app's call to action that will direct the users to TapResearch. To view the available placements or to create a new one, navigate to the app settings in the Supplier Dashboard and copy the placement's identifier.

The Placement is encapsulated in the TRPlacement object which contains metadata and the method to display the survey wall.

An Event is an object that should be attached to the TRPlacement that will prompt the users with a call to action if you have created one in your supplier dashboard for that specific placement. More on event setup can be found here: Sales & Events.


  • The survey wall may or may not be available to a specific user. It's important to check survey availability before displaying the call to action.

Showing a placement

When placementReady has been called then you can call showSurveyWall on the placement you desire:

void showSurveyWall(SurveyListener listener);
void showSurveyWall(SurveyListener listener, PlacementCustomParameters customParameters);

To listen to the survey wall status, add a SurveyListener to the showSurveyWall method.

mPlacement.showSurveyWall(new SurveyListener() {
public void onSurveyWallOpened() {
// Survey wall is visible

public void onSurveyWallDismissed() {
// Survey wall is dismissed

Displaying an Event (New!)

When placementReady has been called then you can call displayEvent on the placement you desire:

void displayEvent(SurveyListener listener);
void displayEvent(SurveyListener listener, PlacementCustomParameters customParameters);

To listen to the event status, add a TapEventListener to the displayEvent method.

//A helper has also been added to verify if an event exists on the available placement. 
mPlacement.displayEvent(new TapEventListener() {
public void onTapEventOpened() {
//Interstitial is visible
public void onTapEventDismissed() {
//Interstitial is dismissed
Note: Calling `displayEvent` will show the first active event on the placement.

Step 6: Handle Rewards

Note: Server to server callbacks: You can read more about server to server callbacks.

The reward information will be encapsulated in the TRReward object or List<TRReward> with the following methods:

Method nameTypeDescription
getTransactionIdentifier()StringThe unique reward identifier
getCurrencyName()StringThe virtual currency name
getPlacementIdentifier()StringThe placement that started the session identifier
getRewardAmount()intThe reward amount in virtual currency.The value will automatically be converted to your virtual currency based on the exchange rate you specified in the app settings.
getPayoutEvent()intThe action that the user was rewarded for. 0 - Profile Complete, 3 - Survey Complete.

(Optional) Custom Parameters

Server to Server callbacks only

Apps that require additional data on server callback can send it using custom parameters. Custom parameters are attached to the placement request and will be fired back in the callback.

To use custom parameters, there are two objects that must be constructed:

  • The PlacementCustomParameters will contain a list of PlacementParameter objects
  • The PlacementParameter which uses the builder design pattern

The parameter object can be added to the PlacementCustomParameters and passed in the showSurveyWall() or displayEvent() calls.

PlacementParameter parameter = new PlacementParameter.Builder().key("foo").value("bar").build();
PlacementCustomParameters parameters = new PlacementCustomParameters();
mPlacement.showSurveyWall(SurveyListener listener, PlacementCustomParameters customParameters);
mPlacement.displayEvent(SurveyListener listener, PlacementCustomParameters customParameters);

Note: both and PlacementCustomParameters.add may throw PlacementCustomParameters.PlacementCustomParametersException to enforce the following rules:

  • Max PlacementParameter character length is 256
  • The PlacementParameter key and value can’t be null and length should be bigger than 0
  • A max of 5 PlacementParameter objects can be placed in PlacementCustomParameters.

(Debug) Troubleshooting

Survey wall isn't available

When placement.isSurveyWallAvailable() returns false, check the logcat for the following message template:

W TRLogTag: [location] Placement isn't available reason - %d, comment - %s

Common reason codes are:

  • 2 - The placement was initialized from a non test device when the app is in test mode
  • 4 - Non-supported country
  • 6 - The app opted for server to server callback but no unique user identifier was set
  • 17 - The placement identifier isn't associated with the App


If you are using proguard to obfuscate your release build and come across any issues, add the following to proguard-rules:

-keep class com.tapr.** { *; }
-keep interface com.tapr.** { *; }

If you have errors with the above, specifically iterator errors and/or Null pointer exceptions try this.

-keep class com.tapr.sdk.** { *; }
-keep class com.tapr.sdk.TapResearch { *; }

And then add the following to your release{} section of your build.gradle

proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), ''
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-tapReasearch.txt'

We recommend not using the proguard-android-optimize.txt file as we have received reports of this causing issues with the SDK.

If you don't want to optimize, use the proguard-android.txt configuration file instead of proguard-android-optimize.txt, Adding optimization introduces certain risks, since not all optimizations performed by ProGuard works on all versions of Dalvik. The following flags turn off various optimizations known to have issues, but the list may not be complete or up to date. (The "arithmetic" optimization can be used if you are only targeting Android 2.0 or later.) Make sure you test thoroughly if you go this route.

Read more about proguard from stack overflow here. And more from google here.

Done: Going Live

Learn how to take the app live.

Enable non-secure URL redirects

TapResearch integrates surveys from a large network of survey providers. While the industry is moving toward full secure https URLs, some large accounts still have legacy systems with insecure URLs. Starting with Android SDK v28, insecure URLs are disabled by default. To ensure that Android users are able to access all of our surveys, please incorporate our URL whitelist into your app.


If your SDK version came before v2.0.10, you'll have to download the whitelist and add it to your project.

  • Download our URL whitelist

  • Copy tapresearch_whitelist.xml to the /res/xml folder in your project

For all SDK versions:

  • In AndroidManifest.xml in the application section, add android:networkSecurityConfig="@xml/tapresearch_whitelist"

Please note that if you used the whitelist before upgrading to v2.0.10, please remove tapresearch_whitelist.xml from the xml folder.


Please send all questions, concerns, or bug reports to