Add the pod information into the app's Podfile.
For XCODE v12 iOS 14 support:
For XCODE v11:
Then run in the Terminal:
You can download the latest version of the SDK from this GitHub page.
TapResearch requires a small number of settings changes that are not included by default.
- Add the TapResearchSDK.framework to the
Link Binary With Librariessection under the Build Phases tab.
- In the same section, add the following frameworks:
Build Settings under the
Other Linker Flags. In the search field, add the following flags:
- -fobjc-arc (Only add this flag if you are not using ARC)
A new protocol has been added which is used by the SDK to let the app know a placement is ready or not available.
It is best to initialize the SDK as early as possible, it is recommend doing it in the
AppDelegate as follows:
Now you are ready to initialize the TapResearch SDK. Add the following line of code inside the
A new initialization method has been added to add passing of a
TapResearchPlacementDelegate object. This is the recommended method for initializing the SDK.
The existing initialization method,
initWithApiToken:delegate, has been deprecated and will be removed in a future version of the SDK.
If you are using in-app rewards, make sure to add
TapResearchRewardDelegate to the
AppDelegate or any
Controller and implement the
tapResearchDidReceiveReward:placement: method to be notified when a player has earned a reward. Also make sure to pass that object to the
The next step is to send a unique user identifier. Keep in mind that without a unique user identifier, the survey wall will not be available.
Our system only accepts User IDs with ASCII characters.
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.
The SDK now 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:
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, you need to call the
showSurveyWallWithDelegate method of the
To listen to the survey wall status, make the placement's
ViewController adopt the
Learn how to take the app live.
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
TapResearchRewardDelegate to the
AppDelegate or any
Controller to be notified when a player has earned a reward. A reward will fire:
tapResearchDidReceiveRewards:placement: method depending on your implementation preference.
The reward information will be encapsulated in the
TRReward object with the following methods:
|transactionIdentifier||NSString||The unique reward identifier|
|currencyName||NSString||The virtual currency name|
|PlacementIdentifier||NSString||The placement that started the session identifier|
|rewardAmount||NSInteger||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.|
|payoutEvent||NSInteger||The action that the user was rewarded for. 0 - Profile Complete, 3 - Survey Complete.|
If you opted for the
tapResearchDidReceiveRewards:placement: to receive multiple rewards your implementation should look like:
It is important to note that
tapResearchDidReceiveReward will be called back-to-back if the player completed multiple surveys in one session.
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
initPlacementWithIdentifier should be called whenever the parent view is loaded.
If you want to use Hot Surveys, please contact email@example.com.
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:
TRPlacementCustomParameterListwill contain a list of
TRPlacementCustomParameterwhich uses the builder design pattern
TRPlacementCustomParameterList, are now passed at the time of showing a placement, no longer when initialising a placement.
TRPlacementCustomParameterList when showing a placement call:
The previous method of passing
TRPlacementCustomParameterList has been deprecated and will be removed in a future version:
TRPlacementCustomParameter.build may return
addParameter may return
NO to enforce the following rules:
TRPlacementCustomParametermax character length is 256
TRPlacementCustomParameterkey and value can’t be null and length should be bigger than 0
TRPlacementCustomParameterListis restricted to maximum of 5
A full example will look like:
If you wish to customize the look of the survey wall modal to fit with the rest of your app, use the following:
Calling theses methods are no longer required for showing placements:
Custom parameters are now called when showing a placement instead of init:
The following method was added to the SDK:
Before you are ready to go live, it is important that your reward callback is working properly. Navigate to your dashboard and click the Add Devices button. Add a device name and your advertiser 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.
placement.isSurveyWallAvailable returns false, check the console output 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
Please send all questions, concerns, or bug reports to firstname.lastname@example.org