Android

Overview

The following should be true prior to calling initialize() on the TapResearchSDK:

• You should have your Listeners implemented to handle reward and placement callbacks.
• You should have the User Identifier set.

Now you can call initialize() on the TapResearchSDK. This will initialize the SDK and check for any unredeemed rewards.

Step 1: Setup

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

Gradle

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

repositories {
  maven { url "https://artifactory.tools.tapresearch.io/artifactory/tapresearch-android-sdk/" }
}

Next, add the following to the module dependencies closure:

dependencies {
  implementation 'com.tapr:tapresearch:2.5.+' // Replace with the latest version
  implementation 'com.google.android.gms:play-services-ads:17.+' //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() {
    @Override
    public void onDidReceiveReward(TRReward reward) {
      String rewardText = String.format("You've earned %d %s for completing a survey.\n%s",
      reward.getRewardAmount(),
      reward.getCurrencyName(),
      reward.getPlacementIdentifier())
      // Your reward logic
    }
};
@Override
public void onResume() {
    TapResearch.getInstance().setRewardListener(rewardListener);
}

@Override
public void onPause() {
    TapResearch.getInstance().setRewardListener(null);
}

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

Configure

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 {
    @Override
    public class onCreate() {
        super.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.

TapResearch.getInstance().setUniqueUserIdentifier(UNIQUE_USER_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.

Availability

• 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() {
    @Override
    public void onSurveyWallOpened() {
       // Survey wall is visible
    }

    @Override
    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. 
if(mPlacement.isEventAvailable()){
    mPlacement.displayEvent(new TapEventListener() {
        @Override
        public void onTapEventOpened() {
            //Interstitial is visible
        }
        @Override
        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 name	Type	Description
getTransactionIdentifier()	String	The unique reward identifier
getCurrencyName()	String	The virtual currency name
getPlacementIdentifier()	String	The placement that started the session identifier
getRewardAmount()	int	The 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()	int	The 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();
parameters.addParameter(parameter)
mPlacement.showSurveyWall(SurveyListener listener, PlacementCustomParameters customParameters);
//OR
mPlacement.displayEvent(SurveyListener listener, PlacementCustomParameters customParameters);

Note: both PlacementParameter.Builder.build 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

Proguard

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'), 'proguard-rules.pro'
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-tapReasearch.txt'

Optimizations

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.

Contact

Please send all questions, concerns, or bug reports to developers@tapresearch.com.