Skip to main content

iOS

Overview​

The following should be true prior to calling initialize() on the TapResearchSDK:

  • You should have your Delegates implemented to handle reward and placement callbacks.
  • You should have the User Identifier set.

Now you can call initialize() on the TapResearchSDK. This will initialize the SDK and check for any unredeemed rewards.

iOS Specific notes​

  • Bitcode is not supported because Apple no longer supports it
  • Only iPad and iPhone are supported
  • Swift version 5.0+ is required
  • We support arm64 processor architecture - this is the default for all iOS devices
    • We also support x86_64 architecture for the simulator

Step 1: Setup​

Install the SDK (Cocoapods)​

Add the pod information into the app's Podfile: pod 'TapResearch','2.5.11'

Be sure to use the latest version of the SDK. You can find the latest version on the releases page

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
    • CoreServices.framework
    • AdSupport.framework
    • Security.framework

Flags​

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

  • -ObjC

Step 2: Delegates​

A new protocol has been added which is used by the SDK to let the app know a placement is ready or not available.

@protocol TapResearchPlacementDelegate <NSObject>
- (void)placementReady:(nonnull TRPlacement *)placement;
- (void)placementUnavailable:(nonnull NSString *)placementId;
@end

The placementReady is fired when a placement has been received and is available to show.

The placementUnavailable is fired when a placement is not currently available. An unavailable placement could become available later and at that time placementReady will be called.

Step 3: Initialize​

It is recommended to initialize the SDK as early as possible 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.

A new initialization method has been added to add passing of a TapResearchPlacementDelegate object. This is the recommended method for initializing the SDK.

+ (void)initWithApiToken:(NSString * _Nonnull)apiToken
          rewardDelegate:(id<TapResearchRewardDelegate> _Nonnull)rewardDelegate
       placementDelegate:(id<TapResearchPlacementDelegate> _Nonnull)placementDelegate;

The previous initialization method, initWithApiToken:delegate, has been deprecated and removed in the latest version of the SDK.

If you are using in-app rewards, make sure to add TapResearchRewardDelegate to the AppDelegate or any ViewController 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}];
}

Step 4: Set User Identifier​

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.

Step 5: Handle 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.

An Event is an object that should be attached to the TRPlacement that will prompt the users with a call to action if you have created one in your supplier dashboard for that specific placement. More on event setup can be found here: Sales & Events.

Showing a placement​

If placementReady has been called for the placement you would like to show then you can just call one of the placement show methods:

- (void)showSurveyWallWithDelegate:(id<TapResearchSurveyDelegate>)surveyDelegate;
- (void)showSurveyWallWithDelegate:(id<TapResearchSurveyDelegate>)surveyDelegate
                  customParameters:(TRPlacementCustomParameterList *)customParameters;

  • 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.

Displaying 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
}

Displaying an Event (New!)​

To display an TREvent, you need to call the displayEvent method of the TRPlacement object.

- (void)displayEvent:(id<TapResearchSurveyDelegate>)surveyDelegate;
- (void)displayEvent:(id<TapResearchSurveyDelegate>)surveyDelegate
                  customParameters:(TRPlacementCustomParameterList *)customParameters;

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

//MainViewController.h
@interface MainViewController : UIViewController<TapResearchSurveyDelegate>

@end
//MainViewController.m
- (void)tapResearchEventOpened:(TRPlacement *)placement
{
  // App went to the background
}

- (void)tapResearchEventDismissed:(TRPlacement *)placement
{
  // Resume app
}

Step 6: Handle 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 ViewController to be notified when a player has earned a reward. A reward will fire: tapResearchDidReceiveRewards: 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.

The tapResearchDidReceiveRewards: receives an array of rewards, your implementation should look like:

// AppDelegate.h

@interface AppDelegate : UIResponder <UIApplicationDelegate, TapResearchRewardDelegate>

- (void)tapResearchDidReceiveRewards:(nonnull NSArray<TRReward *> *)rewards
{
  for (TRReward* reward in rewards) {
    NSString *message = [NSString stringWithFormat:@"You have just received %lu %@ for your efforts.",
    (long)reward.rewardAmount, reward.currencyName];
    //your reward logic
  }
}

(Optional) 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:

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

Custom parameters, TRPlacementCustomParameterList, are now passed at the time of showing a placement, no longer when initialising a placement.

To pass TRPlacementCustomParameterList when showing a placement call:

- (void)showSurveyWallWithDelegate:(id<TapResearchSurveyDelegate>)surveyDelegate
                  customParameters:(TRPlacementCustomParameterList *)customParameters;

The TRPlacementCustomParameterList can also be passed when displaying an event:

- (void)displayEvent:(id<TapResearchSurveyDelegate>)surveyDelegate
                  customParameters:(TRPlacementCustomParameterList *)customParameters;

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

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

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.

(Debug) 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

Done: Going Live​

Learn how to take the app live.

Contact​

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