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)
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
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.
To initialize the placement, it is best practice to call the SDK as late as possible before displaying the placement. For example, you can initialize it in the .m file of the controller where the call to action will be visible to the user.
initPlacementWithIdentifierwas 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, 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
The parameter object can be added to the
TRPlacementCustomParameterList and passed in the
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:
The following method was added to the SDK:
The following methods and protocols were removed from 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