Add the pod info to the app's Podfile
pod 'TapResearch','2.0.12'
pod 'TapResearch','2.1.1'
Then run: $ pod install
You can download the latest version of the TapResearch iOS SDK on GitHub.
TapResearch requires a small number of settings changes that are not included by default.
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];
}
Next step will be to send a unique user identifier, please note that without a unique identifier the survey wall won't be available.
[TapResearch setUniqueUserIdentifier:@"UNIQUE_USER_IDENTIFIER"];
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.
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
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.
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 Survey please contact
developers@tapresearch.comdevelopers@tapresearch.com.
To opt in for server to server postbacks, navigate to the supplier dashboard. Please visit API docs to learn about postbacks integration.
###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.
Apps that require additional data on server postback can send it using custom parameters. Custom parameters are attached to the placement request and will be fired back in the postback.
To use the feature there are 2 object that will be constructed:
TRPlacementCustomParameterList an object that will contain
a list of TRPlacementCustomParameter objects.
TRPlacementCustomParameter 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 that
TRPlacementCustomParameter.build may return nil and
TRPlacementCustomParameterList addParameter may return NO
to enforce the following rules:
TRPlacementCustomParameter max character length is
256TRPlacementCustomParameter key and value can’t be
null and length should be bigger than 0TRPlacementCustomParameterList is restricted to maximum
of 5 TRPlacementCustomParameter objectsA 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) {
...
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];];
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>
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.
###Survey wall isn't available {#no-surveys} 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:
Please send all questions, concerns, or bug reports to developers@tapresearch.com
