Skip to main content
Version: 3.x

iOS Survey Wall Preview

Test Mode

If your app is in test mode, you must use a test user. Configure test users in "Test Devices" on the dashboard.

Installation​

See here for TapResearch SDK for iOS integration documentation.

Example apps are available here

Before You Begin​

  • You must be on SDK v3.4.2+ to have access to Survey Wall Preview.
  • 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
  • Survey wall preview 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 survey wall preview interfaces
  • Implement the TapResearchSurveysDelegate delegate callback onTapResearchSurveysRefreshedForPlacement and set it before calling getSurveys, showSurveyWithSurveyId or showSurvey functions.
Support

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

Introduction​

Survey wall preview allows you to 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 survey_identifier: 'profile'
  • Display example:
Profile tile preview

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"

  // 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:
Tiles preview

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:
Hot tile

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:
Currency Sale Preview

Integration​

SDK Interfaces​

Checking for available surveys​

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

View in context

TapResearch.hasSurveys(for placementTag: <#String#>, errorHandler: <#((NSError?) -> Void)? = nil#>) -> Bool {
}

Getting available surveys​

Get the surveys for your placement.

Note: Attempting to fetch surveys before receiving the SDK Ready callback will result in an error and no surveys will be returned.

View in context

TapResearch.getSurveys(for placementTag: <#String#>, errorHandler: <#((NSError?) -> Void)? = nil#>) -> [TRSurvey] {
}

Check that a survey can be shown​

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

View in context

TapResearch.canShowSurvey(surveyId: <#String#>, forPlacementTag placementTag: <#String#>) -> Bool {
}

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, for more information about these callbacks see here.

View in context

TapResearch.showSurvey(surveyId: <#String#>,
                       forPlacementTag placementTag: <#String#>,
                       delegate: <#TapResearchContentDelegate#>,
                       errorHandler: <#((NSError?) -> Void)? = nil#>)
{
}

If you need to pass custom parameters use:

View in context

TapResearch.showSurvey(surveyId: <#String#>,
                       forPlacementTag placementTag: <#String#>,
                       delegate: <#TapResearchContentDelegate#>,
                       customParameters: <#[AnyHashable:Any]#>,
                       errorHandler: <#((NSError?) -> Void)? = nil#>)
{
}

Callback​

Survey Wall Preview adds a required callback that lets you know when surveys have been refreshed.

Setting the delegate​

Required: Set the delegate using setSurveysDelegate before calling getSurveys, showSurveyWithSurveyId or showSurvey functions.

If the delegate is not set the SDK will send errors using the TapResearchSDKDelegate error callback onTapResearchDidError and Survey Wall Previews will not work.

View in context

TapResearch.setSurveysDelegate(_ delegate: <#TapResearchSurveysDelegate?#>) {
}

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:

View in context

func onTapResearchSurveysRefreshed(forPlacement placementTag: String) {
}