iOS Native Survey Tiles

Test mode

If your app is in test mode, you must use a test user. Add test users in the Publisher Dashboard under More → Test devices.

Installation

Start with the iOS integration guide if you haven't set up the SDK yet.

See the Native Survey Tiles example app on GitHub.

Before you begin

• You must be on SDK v3.4.2+ to have access to Native Survey Tiles.
• The wall preview feature needs to be enabled and set up by the TapResearch team so please reach out to your account manager when you are ready to get started
• Native Survey Tiles should be on a dedicated placement, separate from the standard Survey Wall (if applicable)
• Always wait until the SDK is ready (via the onTapResearchSdkReady callback or by checking TapResearch.isReady()) before calling any Native Survey Tiles interfaces
• Set a TapResearchSurveysDelegate (its onTapResearchSurveysRefreshed(forPlacement:) method) before calling getSurveys or showSurvey, so your app hears when the surveys change.

Support

Any other questions? Reach out to your account manager or via Slack and we'll be happy to help!

Introduction

Native Survey Tiles (formerly Survey Wall Preview) let you provide users with available surveys, directly inside your app. Some benefits of this include:

• Custom UI — Create your own UI presentation with survey tiles/cards
• Direct survey access — Provide users with direct entry into surveys they choose

---

Key considerations & UI design

When designing your survey tiles/cards, consider these elements:

1. The profile survey

New users must complete the introductory profile survey before they can access other surveys. For these new users, the SDK will return only this survey until they have completed it.

• Only shown to users that are new to TapResearch
• Will always be returned by itself, with a survey identifier of profile
• Display example:

2. Survey details

After completing the profile survey, users should then start receiving real surveys. Surveys will have the following attributes:

@objc public final class TRSurvey : NSObject, Codable {
  // Primary attributes
  @objc public let surveyIdentifier    : String // Unique identifier, will be used when a user taps on a survey
  @objc public let lengthInMinutes     : Int    // The estimated time to complete the survey
  @objc public let rewardAmount        : Double // The reward amount for taking the survey
  @objc public let currencyName        : String // The name of the reward currency
  @objc public let isHotTile           : Bool   // Whether the survey should be designated as a "hot tile"
  @objc public let category            : String? // The survey's category, if it has one

  // Sale attributes
  @objc public let isSale              : Bool    // Whether a currency sale is currently active
  @objc public let saleMultiplier      : Double  // The multiplier being applied to the sale
  @objc public let saleEndDate         : String? // If a sale is active, the UTC date it will end
  @objc public let preSaleRewardAmount : Double  // The pre-multiplier reward amount, for enhancing UI during a sale
}

• We recommend displaying all primary data points to allow users to choose which survey length/reward they want
• Display example:

3. "Hot" tiles

Hot tiles are surveys with exceptional scores, typically offering the best time-to-reward ratio. Displaying a special UI highlight for these surveys is recommended, as they tend to increase user engagement and click-through rates.

• Display example:

4. Currency Sales

When running promotional currency sales, the relevant sale attributes of the survey object will populate, allowing you to show enhanced UIs and CTAs to users. We recommend using this data to display the extra rewards boost on the individual tiles.

• Display example:

---

Integration

SDK interfaces

Checking for available surveys

When you have received notification that the SDK is ready (see Checking if the SDK is ready) you should first check if there are surveys available for your placement:

Swift

let hasSurveys: Bool = TapResearch.hasSurveys(for: placementTag) { (error: NSError?) in
    // Optional: handle the error
}

Objective-C

BOOL hasSurveys = [TapResearch hasSurveysFor:placementTag errorHandler:^(NSError * _Nullable error) {
    // Optional: handle the error
}];

Getting available surveys

Get the surveys for your placement.

Note: Fetch surveys only after receiving the SDK Ready callback.

Swift

let surveys: [TRSurvey] = TapResearch.getSurveys(for: placementTag)

Objective-C

NSArray<TRSurvey *> *surveys = [TapResearch getSurveysFor:placementTag errorHandler:nil];

Check that a survey can be shown

Before showing, it is always best to check if the survey can be shown using canShowSurvey:

Swift

let canShow: Bool = TapResearch.canShowSurvey(surveyId: survey.surveyIdentifier, forPlacementTag: placementTag)

Objective-C

BOOL canShow = [TapResearch canShowSurveyWithSurveyId:survey.surveyIdentifier forPlacementTag:placementTag];

Showing a survey

Showing a survey works similarly to showContent used for showing TapResearch survey content: after checking if a survey can be shown, call showSurvey with a survey ID, placement tag and a content delegate to receive onTapResearchContentShown and onTapResearchContentDismissed callbacks, see TapResearchContentDelegate for details.

Swift

TapResearch.showSurvey(surveyId: survey.surveyIdentifier,
                       placementTag: placementTag,
                       delegate: self) { (error: NSError?) in
    // Handle the error
}

Objective-C

[TapResearch showSurveyWithSurveyId:survey.surveyIdentifier
                       placementTag:placementTag
                           delegate:self
                       errorHandler:^(NSError * _Nullable error) {
    // Handle the error
}];

If you need to pass custom parameters use:

Swift

TapResearch.showSurvey(surveyId: survey.surveyIdentifier,
                       placementTag: placementTag,
                       delegate: self,
                       customParameters: ["param1": 123, "param2": "abc"]) { (error: NSError?) in
    // Handle the error
}

Objective-C

[TapResearch showSurveyWithSurveyId:survey.surveyIdentifier
                       placementTag:placementTag
                           delegate:self
                   customParameters:@{@"param1": @123, @"param2": @"abc"}
                       errorHandler:^(NSError * _Nullable error) {
    // Handle the error
}];

Callback

Native Survey Tiles adds a callback that lets you know when surveys have been refreshed.

Setting the delegate

Set the delegate using setSurveysDelegate before calling getSurveys or showSurvey. Without it, your app isn't told when the surveys for a placement change.

Swift

TapResearch.setSurveysDelegate(self)

Objective-C

[TapResearch setSurveysDelegate:self];

To remove the delegate call the setSurveysDelegate with nil.

Handling the callback

You will see calls to the callback function when surveys have been completed, after any TapResearch content has been dismissed.

Make sure the delegate object implements TapResearchSurveysDelegate and updates local storage and displays with the updated surveys:

Swift

func onTapResearchSurveysRefreshed(forPlacement placementTag: String) {
    let surveys: [TRSurvey] = TapResearch.getSurveys(for: placementTag)
    // Update your survey tiles
}

Objective-C

- (void)onTapResearchSurveysRefreshedForPlacement:(NSString *)placementTag {
    NSArray<TRSurvey *> *surveys = [TapResearch getSurveysFor:placementTag errorHandler:nil];
    // Update your survey tiles
}