Android SDK

Getting Started#

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 {
compile 'com.tapr:tapresearch:2.3.0'
...
}

And synchronize the project with the gradle files.

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:

dependencies {
implementation 'com.google.android.gms:play-services-ads:17.+'
...
}

TapResearchSDK v2.3.0 introduces a new way of getting and showing placements.#

The SDK now internally gets the placements that are available for your app, caches them and lets you know when they are ready or become unavailable.

PlacementEventListener#

A new interface has been added which is used by the SDK to let the app know a placement is ready or not available.

public interface PlacementEventListener {
void placementReady(TRPlacement placement);
void placementUnavailable(String placementId);
}
`placementReady` is called when a placement has been received and is available to show.`placementUnavailable` is called when a placement is not currently available. An unavailable placement could become available later and at that time `placementReady` will be called.

v.2.3.0 Note: placementExpired has been deprecated in place of placementUnavailable.

Initialize TapResearch#

A new initialization method has been added in v2.3.0 to add passing of a PlacementEventListener object. This is the recommended method for initializing the SDK.

public void configure(String apiToken, Application application,PlacementEventListener placementEventListener)

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. Please note that that the configure() method only needs to be called once.

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

The next step will be to send a unique user identifier. Please note that without a unique identifier, the survey wall won't be available.

TapResearch.getInstance().setUniqueUserIdentifier(UNIQUE_USER_IDENTIFIER);

Our system only accepts User IDs with ASCII characters. If necessary, you can convert it to BASE64 before sending the User ID to us.

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.

Showing a placement#

Previously when showing a placement the placement had to be initialized first by calling one of the initPlacement SDK methods:

public abstract void initPlacement(@NonNull String placementIdentifier, @NonNull PlacementListener placementListener);
public abstract void initPlacement(@NonNull String placementIdentifier, PlacementCustomParameters customParameters, @NonNull PlacementListener placementListener);

This is no longer required, the SDK initializes placements for you internally.

If placementReady has been called for the placement you would like to show then you can just call one of the placement show methods:

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

More About Placements#

  • If initPlacement was called before the SDK initialization was completed, the SDK will return two placements: the first will return a placementCode with a value of PLACEMENT_CODE_SDK_NOT_READY and won't display the survey wall. The second placement response will occur once the SDK is initialized. The placement request will be fired and the callback will be triggered with a live placement.

  • 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.

  • A placement can only show the survey wall once. After the survey wall is dismissed, you'll have to initialize a new TRPlacement object if you want the user to go back to TapResearch.

Display the survey wall#

To display the survey wall, call the showSurveyWall method of the TRPlacement object.

mPlacement.showSurveyWall(null);

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
}
});

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.

Details:

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.

Rewards#

Server to server callbacks#

You can read more about server to server callbacks.

In-app callback#

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

  • On SDK initialization
  • When the user exits TapResearch

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. TapResearch.getInstance().setRewardCollectionListener to receive rewards as a collection.

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.

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);
}

If you opted for the RewardCollectionListener to receive multiple rewards your implementation should look like:

RewardCollectionListener rewardCollectionListener = new RewardCollectionListener() {
@Override
public void onDidReceiveReward(List<TRReward> rewards) {
for (TRReward reward : rewards){
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().setRewardCollectionListener(rewardCollectionListener);
}
@Override
public void onPause() {
TapResearch.getInstance().setRewardCollectionListener(null);
}

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

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:

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

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

PlacementParameter parameter = new PlacementParameter.Builder().key("foo").value("bar").build();
PlacementCustomParameters parameters = new PlacementCustomParameters();
parameters.addParameter(parameter)
//As of v2.3.0 you can pass parameters when calling showSurveyWall with your placement.
mPlacement.showSurveyWall(SurveyListener listener, PlacementCustomParameters customParameters);

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

  • PlacementParameter max character length is 256
  • The PlacementParameter key and value can’t be null and length should be bigger than 0
  • PlacementCustomParameters is restricted to a maximum of 5 PlacementParameter objects

A full example will look like:

PlacementCustomParameters parameters = new PlacementCustomParameters();
try {
parameters.addParameter(new PlacementParameter.Builder().key("foo").value("bar").build());
parameters.addParameter(new PlacementParameter.Builder().key("fuzz").value("buzz").build());
} catch (PlacementCustomParameters.PlacementCustomParametersException e) {
e.printStackTrace();
}
TapResearch.getInstance().initPlacement(offerIdentifier, parameters, new PlacementListener() {
...

Hot Survey#

hasHotSurvey is a placement attribute that indicates a special high-yield survey is available for this user. When this attribute is true, the user should be shown a special call to action to encourage them to take advantage of this opportunity. These special survey opportunities may only be available for a few minutes, so initPlacement should be called whenever the parent view is loaded. If you want to use Hot Surveys, please contact developers@tapresearch.com.

Customizing the SurveyActivity look#

You can use the following two ways to customize the look of the SurveyActivity:

  • Apply a theme:
<activity
tools:replace="android:theme"
android:theme="@android:style/Theme.Holo.Light.DarkActionBar"
android:name="com.tapr.internal.activities.survey.SurveyActivity"
android:configChanges="orientation|keyboardHidden|screenSize"
android:hardwareAccelerated="true"
/>
  • Use the following methods:
TapResearch.getInstance().setActionBarColor(getResources().getColor(R.color.colorPrimary));
TapResearch.getInstance().setActionBarText("Title");
TapResearch.getInstance().setActionBarTextColor(getResources().getColor(R.color.colorAccent));

Upgrade To v2.3.0#

The following interface was added to the SDK:

public void configure(String apiToken, Application application, PlacementEventListener placementEventListener)

Calling this method is no longer required for showing placements:

public abstract void initPlacement(@NonNull String placementIdentifier, @NonNull PlacementListener placementListener);

Custom parameters are now called when showing a placement instead of init.

void showSurveyWall(SurveyListener listener, PlacementCustomParameters customParameters);

Upgrade To v2.2.2#

The following interface was added to the SDK:

public interface RewardCollectionListener {
void onDidReceiveReward(List<TRReward> rewards);
}

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.** { *; }

Test Devices#

Before you are ready to go live, the SDK can only work with a test device. Navigate to your dashboard and click the Add Devices button. Add a device name and a unique user identifier or a Google Advertising ID / Apple IDFA. Now, when you enter our survey flow through your app, you will be able to complete a test survey and receive a test reward when you re-open your app.

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

Android build failed due to a manifest conflict#

If the Android build failed because the android:allowBackup attribute is conflicting, add tools:replace="allowBackup" to the Application section.

Contact#

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