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.0.14'
...
}
And synchronize the project with the gradle files.
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.+'
...
}
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 as shown below.
public class MyApp extends Application {
@Override
public class onCreate() {
super.onCreate();
TapResearch.configure(YOUR_API_TOKEN, this);
}
}
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(SOME_UNIQUE_USER_IDENTIFIER);
A placement is the allocated section in your application where you want to provide access to TapResearch's survey wall, like an action button or a list item. To create a placement, navigate to the app settings in the supplier dashboard, click settings and add the placement. The placement is encapsulated by the TRPlacement object which contains the placement metadata and the method to display the survey wall.
To initialize the placement, it is best practice to call the SDK as late as possible before displaying the placement in the app. For example, you can initialize it in the onResume
Activity / Fragment method where the placement will be visible.
private TRPlacement mPlacement;
@Override
public void onResume() {
TapResearch.getInstance().initPlacement(PLACEMENT_IDENTIFIER, new PlacementListener() {
@Override
public void onPlacementReady(TRPlacement placement) {
if (placement.getPlacementCode() != TRPlacement.PLACEMENT_CODE_SDK_NOT_READY) {
mPlacement = placement;
if (mPlacement.isSurveyWallAvailable()) {
// If there are surveys available for the user, display the placement
}
} else {
//SDK is not ready
}
}
});
...
}
The survey wall may or may not be available to a specific user and it's important to check survey availability before displaying the placement.
Please note that if the placement request was fired before that SDK is ready the PlacementListener
will be called twice. The first time getPlacemenCode() will return TRPlacement.PLACEMENT_CODE_SDK_NOT_READY indicating that the request was fired
before the SDK was ready, the second call will return the latest placement from the server.
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
}
});
Please Note: A placement can only show the survey wall one time. Once the survey wall is dismissed, you'll have to initialize a new TRPlacement object if you wish to keep the placement visible in the app.
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
tapresearch_whitelist.xml to the /res/xml folder in your projectFor all SDK versions
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.
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 Survey please contact developers@tapresearch.comdevelopers@tapresearch.com.
To opt in for server to server postbacks, navigate to the supplier dashboard. Please visit API docs to learn about postbacks integration.
Create a reward listener so we can notify you when a user completes a survey. The quantity value will automatically be converted to your virtual currency based on the exchange rate you specified in your app settings. It is important to note that this method may be called back-to-back if the player completed multiple surveys in one session.
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
}
};
public void onResume() {
TapResearch.getInstance().setRewardListener(rewardListener);
}
Apps that require additional data on server postback can send it using custom parameters. Custom parameters are attached to the placement request and will be fired back in the postback.
To use the feature there are 2 object that will be constructed: PlacementCustomParameters an object that will contain a list of PlacementParameter objects.
PlacementParameter uses the builder design pattern
The parameter object can be added to the PlacementCustomParameters and passed in the InitPlacement call
PlacementParameter parameter = new PlacementParameter.Builder().key("foo").value("bar").build();
PlacementCustomParameters parameters = new PlacementCustomParameters();
parameters.addParameter(parameter)
TapResearch.getInstance().initPlacement(offerIdentifier, parameters, new PlacementListener() {
...
Note that both PlacementParameter.Builder.build and PlacementCustomParameters.add may throw PlacementCustomParameters.PlacementCustomParametersException to enforce the following rules
PlacementParameter max character length is 256PlacementParameter key and value can’t be null and length should be bigger than 0PlacementCustomParameters is restricted to maximum of 5 PlacementParameter objectsA full example will look like
PlacementCustomParameters parameters = new PlacementCustomParameters();
try {
parameters.addParameter(newPlacementParameter.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() {
...
You can use the following two ways to customise the look of the SurveyActivity:
<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"
/>
TapResearch.getInstance().setActionBarColor(getResources().getColor(R.color.colorPrimary));
TapResearch.getInstance().setActionBarText("Title");
TapResearch.getInstance().setActionBarTextColor(getResources().getColor(R.color.colorAccent));
The following methods and interfaces were removed from the SDK:
public abstract boolean isSurveyAvailable();
public abstract boolean isSurveyAvailable(String offerIdentifier);
public abstract void showSurvey();
public abstract void showSurvey(String offerIdentifier);
public abstract void setOnRewardListener(TapResearchOnRewardListener listener);
public abstract void setSurveyListener(TapResearchSurveyListener listener);
public abstract void setPlacementsListener(TapResearchPlacementsListener listener);
public interface TapResearchOnRewardListener
public interface TapResearchPlacementsListener
public interface TapResearchSurveyListener
Please remove the following from AndroidManifest.xml:
<activity android:name="com.tapr.internal.c.TRSurveyActivity" android:hardwareAccelerated="true" android:configChanges="orientation|keyboardHidden|screenSize" android:theme="@android:style/Theme.Holo.Light" />
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.** { *; }
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 your Google Advertising ID or a unique user identifier. 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.
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:
Please send all questions, concerns, or bug reports to developers@tapresearch.com.
