iOS SDK

Getting Started#

Install the SDK (Cocoapods)#

Add the pod information into the app's Podfile.

For XCODE v12 iOS 14 support: pod 'TapResearch','2.1.5'

For XCODE v11: pod 'TapResearch','2.0.15'

Then run in the Terminal: pod install

Install the SDK (Manually)#

You can download the latest version of the SDK from this GitHub page.

Xcode Project Setup#

TapResearch requires a small number of settings changes that are not included by default.

Libraries#

  • Add the TapResearchSDK.framework to the Link Binary With Libraries section under the Build Phases tab.
  • In the same section, add the following frameworks:
    • Foundation.framework
    • UIKit.framework
    • SystemConfiguration.framework
    • MobileCoreServices.framework
    • AdSupport.framework
    • Security.framework

Flags#

Select the Build Settings under the Other Linker Flags. In the search field, add the following flags:

  • -ObjC
  • -fobjc-arc (Only add this flag if you are not using ARC)

Initialize TapResearch#

It is best to initialize the SDK as early as possible, it is recommend doing it in the AppDelegate as follows:

// AppDelegate.h
#import <TapResearchSDK/TapResearchSDK.h>
@interface AppDelegate : UIResponder <UIApplicationDelegate>

Now you are ready to initialize the TapResearch SDK. Add the following line of code inside the applicationDidFinishLaunchingWithOptions method.

// AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
// Your code logic
[TapResearch initWithApiToken:#{API_TOKEN} delegate:nil];
}

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 initWithAppToken:delegate method:

// AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
// Your code logic
[TapResearch initWithApiToken:#{API_TOKEN} delegate:#{TapResearchRewardDelegate object}];
}

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.

[TapResearch setUniqueUserIdentifier:@"UNIQUE_USER_IDENTIFIER"];

Our system only accepts User IDs with ASCII characters.

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.

Initialize a placement#

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.

#import <TapResearchSDK/TapResearchSDK.h>
@interface MainTableViewController ()
@property (nonatomic, strong) TRPlacement *tapresearchPlacement;
@end
- (void)viewDidLoad
{
[super viewDidLoad];
[TapResearch initPlacementWithIdentifier:PLACEMENT_IDENTIFIER placementBlock:^(TRPlacement *placement) {
self.tapresearchPlacement = placement;
if (self.tapResearchPlacement.placementCode != PLACEMENT_CODE_SDK_NOT_READY) {
if (self.tapResearchPlacement.isSurveyWallAvailable == YES) {
// If there are surveys available for the user display the placement
}
} else {
// SDK is not ready
}
}];
...
}

More About Placements#

  • If initPlacementWithIdentifier 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, you need to call the showSurveyWallWithDelegate method of the TRPlacement object.

- (IBAction)surveyButtonTouched:(id)sender
{
[self.tapresearchPlacement showSurveyWallWithDelegate:nil];
}

To listen to the survey wall status, make the placement's ViewController adopt the TapResearchSurveyDelegate:

//MainViewController.h
@interface MainViewController : UIViewController<TapResearchSurveyDelegate>
@end
//MainViewController.m
- (IBAction)surveyButtonTouched:(id)sender
{
[self.tapresearchPlacement showSurveyWallWithDelegate:self];
}
- (void)tapResearchSurveyWallOpenedWithPlacement:(TRPlacement *)placement
{
// App went to the background
}
- (void)tapResearchSurveyWallDismissedWithPlacement:(TRPlacement *)placement
{
// Resume app
}

Going Live#

Learn how to take the app live.

Rewards#

Server to server callbacks#

You can read more about server to server callbacks.

In-app Callbacks#

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

  • On SDK initialization
  • When the user exits TapResearch

Add TapResearchRewardDelegate to the AppDelegate or any Controller to be notified when a player has earned a reward. A reward will fire the tapResearchDidReceiveReward:placement: method.

The reward information will be encapsulated in the TRReward object with the following methods:

Property nameTypeDescription
transactionIdentifierNSStringThe unique reward identifier
currencyNameNSStringThe virtual currency name
PlacementIdentifierNSStringThe placement that started the session identifier
rewardAmountNSIntegerThe 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.
payoutEventNSIntegerThe action that the user was rewarded for. 0 - Profile Complete, 3 - Survey Complete.

// AppDelegate.h
@interface AppDelegate : UIResponder <UIApplicationDelegate, TapResearchRewardDelegate>
- (void)tapResearchDidReceiveReward:(TRReward *)reward
{
NSString *message = [NSString stringWithFormat:@"You have just received %lu %@ for your efforts.",
(long)reward.rewardAmount, reward.currencyName];
...
}

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

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 initPlacementWithIdentifier should be called whenever the parent view is loaded. If you want to use Hot Surveys, please contact developers@tapresearch.com.

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:

  • TRPlacementCustomParameterList will contain a list of TRPlacementCustomParameter objects
  • TRPlacementCustomParameter which uses the builder design pattern

The parameter object can be added to the TRPlacementCustomParameterList and passed in the initPlacementWithIdentifier call.

TRPlacementCustomParameterList *parameterList = [[TRPlacementCustomParameterList alloc] init];
TRPlacementCustomParameter *param = [TRPlacementCustomParameter new];
[[[[param builder] key: @"foo"] value: @"bar"] build];
[parameterList addParameter:param];
[TapResearch initPlacementWithIdentifier:identifier placementCustomParameters:parameterList placementBlock:^(TRPlacement *placement)
...

Note: TRPlacementCustomParameter.build may return nil and TRPlacementCustomParameterList addParameter may return NO to enforce the following rules:

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

A full example will look like:

TRPlacementCustomParameter *param = [TRPlacementCustomParameter new];
[[[[param builder] key: @"foo"] value: @"bar"] build];
TRPlacementCustomParameterList *parameterList = [[TRPlacementCustomParameterList alloc] init];
[parameterList addParameter:param];
[TapResearch initPlacementWithIdentifier:identifier placementCustomParameters: parameterList placementBlock:^(TRPlacement *placement) {
...

Customize the survey wall#

If you wish to customize the look of the survey wall modal to fit with the rest of your app, use the following:

[TapResearch setNavigationBarText:@"Title"];
[TapResearch setNavigationBarColor:[UIColor colorWithRed:1.0f green:0.5f blue:0.5f alpha:1.0f];];
[TapResearch setNavigationBarTextColor:[UIColor colorWithRed:0.5f green:0.5f blue:1.0f alpha:1.0f];];

Upgrade to v2.0.0#

The following methods and protocols were removed from the SDK:

+ (BOOL)isSurveyAvailable;
+ (BOOL)isSurveyAvailableForIdentifier:(NSString *)identifier;
+ (void)showSurvey;
+ (void)showSurveyWithDelegate:(id<TapResearchSurveyDelegate>)delegate
+ (void)showSurveyWithIdentifier:(NSString *)identifier delegate:(id<TapResearchSurveyDelegate>)surveyDelegate;
@protocol TapResearchDelegate <NSObject>
@protocol TapResearchSurveyDelegate <NSObject>

Test Devices#

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.

Troubleshooting#

Survey wall isn't available#

When placement.isSurveyWallAvailable returns false, check the console output for the following message template:

"Placement isn't available reason - %lu, comment - %@"

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

Contact#

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