Add the following to the repositories closure of the app's module
Next, add the following to the module dependencies closure:
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
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.
A new interface has been added which is used by the SDK to let the app know a placement is ready or not available.
placementExpired has been deprecated in place of
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.
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.
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.
Our system only accepts User IDs with ASCII characters. If necessary, you can convert it to BASE64 before sending the User ID to us.
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.
Placement is encapsulated in the
TRPlacement object which contains metadata and the method to display the survey wall.
Previously when showing a placement the placement had to be initialized first by calling one of the
initPlacement SDK methods:
This is no longer required, the SDK initializes placements for you internally.
placementReady has been called for the placement you would like to show then you can just call one of the placement show methods:
initPlacementwas called before the SDK initialization was completed, the SDK will return two placements: the first will return a
placementCodewith a value of
PLACEMENT_CODE_SDK_NOT_READYand 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
TRPlacementobject if you want the user to go back to TapResearch.
To display the survey wall, call the
showSurveyWall method of the
To listen to the survey wall status, add a
SurveyListener to the
Learn how to take the app live.
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
/res/xmlfolder in your project
For all SDK versions:
- In AndroidManifest.xml in the
Please note that if you used the whitelist before upgrading to v2.0.10, please remove
tapresearch_whitelist.xml from the xml folder.
You can read more about server to server callbacks.
The SDK will check if the user has unredeemed rewards in the following events:
- On SDK initialization
- When the user exits TapResearch
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:
|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.|
If you opted for the
RewardCollectionListener to receive multiple rewards your implementation should look like:
It is important to note that
onDidReceiveReward will be called back-to-back if the player completed multiple surveys in one session.
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:
PlacementCustomParameterswill contain a list of
PlacementParameterwhich uses the builder design pattern
The parameter object can be added to the
PlacementCustomParameters and passed in the
PlacementCustomParameters.add may throw
PlacementCustomParameters.PlacementCustomParametersException to enforce the following rules:
PlacementParametermax character length is 256
PlacementParameterkey and value can’t be null and length should be bigger than 0
PlacementCustomParametersis restricted to a maximum of 5
A full example will look like:
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 firstname.lastname@example.org.
You can use the following two ways to customize the look of the SurveyActivity:
- Apply a theme:
- Use the following methods:
The following interface was added to the SDK:
Calling this method is no longer required for showing placements:
Custom parameters are now called when showing a placement instead of init.
The following interface was added to the SDK:
If you are using proguard to obfuscate your release build and come across any issues, add the following to
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.
placement.isSurveyWallAvailable() returns false, check the logcat for the following message template:
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 the Android build failed because the
android:allowBackup attribute is conflicting, add
tools:replace="allowBackup" to the Application section.
Please send all questions, concerns, or bug reports to email@example.com.