TapResearch iOS Integration Guide

Getting Started

Install the SDK (Cocoapods)

Add the pod info to the app's Podfile pod 'TapResearch','2.0.6'

Then run the following command: $ pod install

Install the SDK (Manually)

You can download the latest version of the TapResearch iOS SDK on GitHub.

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 tab and type in 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

After you have finished modifying the project settings, open your AppDelegate.h file and add the following lines of code.


  // 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:YOUR_API_TOKEN delegate:nil];
  }

Placements

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.

Initialize a placement

To initialize a 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 .m file of the controller where the placement 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
    }
  }];

  ...
}

Notice that 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 placementBlock will be called twice. The first time placement.placementCode will return 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

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
}

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.

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.

Rewards

Server to server postback

If you did not opt for server to server postbacks, go to in-app callback If you set a postback URL for your app, you will be required to pass us a unique user identifier through the method shown below. This identifier will be included inside the postback payload.


  [TapResearch setUniqueUserIdentifier:@"UNIQUE_USER_IDENTIFIER"];

In-app callback

Add the TapResearchRewardDelegate to allow us to notify you when a player has earned a reward. Add the tapResearchDidReceiveReward:placement: method. Please note: if the app is set to "server to server" the "in-app" callback won't be fired.


// AppDelegate.h

@interface AppDelegate : UIResponder <UIApplicationDelegate, TapResearchRewardDelegate>


@end

// AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Your code logic
    [TapResearch initWithApiToken:YOUR_API_TOKEN delegate:self];
}


- (void)tapResearchDidReceiveReward:(TRReward *)reward
{
    NSString *message = [NSString stringWithFormat:@"You have just received %lu %@ for your efforts.",
      (long)reward.rewardAmount, reward.currencyName];
    ...
}

All the reward information is encapsulated in the TRReward object. The rewardAmount 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.

Customise the survey wall

If you wish to customise 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 out 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 is opted for server to server postback 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

FAQ

Do we have to pay to use the TapResearchSDK?

No. Our SDK is completely free of charge. In fact, we pay you every time a user completes a survey.

What measures do you take to protect user privacy?

We take user privacy very seriously. All data is encrypted before being sent over the network. Furthermore, we use HTTPS to ensure the integrity and privacy of the exchanged data.

What kind of analytics do I have access to?

Our dashboard will show metrics for sessions, impressions, revenue, and much more. We are constantly enhancing our analytics so we can better serve your needs.

What is your fill rate?

We have thousands of surveys and add a few hundred more every day. Most users will have the opportunity to complete at least one survey on a daily basis.

I'm ready to go live! What are the next steps?

Let us know! We need to update the status of your app so your users can see real surveys. Note, test devices will only be able to see a test survey.