Skip to main content
Version: 3.x

Android 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​

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

data class TRSurvey(
  // Primary attributes
  val surveyId: String? = null, // Unique identifier, will be used when a user taps on a survey
  val lengthInMinutes: Int? = null, // The estimated time to complete the survey
  val rewardAmount: Float? = null, // The reward amount for taking the survey
  val currencyName: String? = null, // The name of the reward currency
  val isHotTile: Boolean? = null, // Whether the survey should be designated as a "hot tile"

  // Sale attributes
  var isSale: Boolean? = null, // Whether a currency sale is currently active
  var saleEndDate: String? = null, // If a sale is active, the UTC date it will end
  var saleMultiplier: Float? = null, // The multiplier being applied to the sale
  var preSaleRewardAmount: Float? = null, // 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​

The code below demonstrates how to:

  1. Fetch surveys after SDK initialization
  2. Set up a surveys refreshed listener (required)

Key points:

  • Fetch surveys only after the SDK Ready event
  • Render the TRSurvey objects in your UI (see handleMySurveys function)
  • Required: Set the surveys refreshed listener to get updates when surveys change
danger

Attempting to fetch surveys before SDK Ready will result in an error and no surveys will be returned.

        TapResearch.initialize(
          apiToken = "my-api-token",
          userIdentifier = "my-user-identifier",
          context = this@MainActivity,
          errorCallback = { error -> handleMyError(error) },
          sdkReadyCallback = {
            Log.d(LOG_TAG, "SDK is ready")
        
            // Surveys can be fetched anytime after SDK Ready
            val surveys = TapResearch.getSurveysForPlacement("my-placement-tag"){}
            handleMySurveys(surveys) // your surveys handler; handle null or empty list
        
            // REQUIRED: Set your surveys refreshed listener 
            TapResearch.setSurveysRefreshedListener(object: TRSurveysRefreshedListener{
              override fun onSurveysRefreshedForPlacement(placementTag: String) {
                if (placementTag == "my-placement-tag") {
                    val updatedSurveys = TapResearch.getSurveysForPlacement(placementTag) {}
                    handleMySurveys(updatedSurveys) // your surveys handler; handle null or empty list
                }  
              }
            })
          },
          rewardCallback = handleMyRewards,
          initOptions = null,
          qqDataCallback = null,
        )

Showing a survey​

You will need the surveyId from the TRSurvey object in order to show the survey:

TapResearch.showSurveyForPlacement(
    placementTag = "my-placement-tag",
    surveyId = survey.surveyId, // from TRSurvey object
    customParameters = null,
    contentListener = object : TRContentCallback {
        override fun onTapResearchContentShown(placementTag: String) {
            // survey is being shown
        }

        override fun onTapResearchContentDismissed(placementTag: String) {
            // survey was dismissed
        }
    },
    errorListener = object : TRErrorCallback {
        override fun onTapResearchDidError(trError: TRError) {
            // a rare error occurred while showing the survey
        }
    }
)

Passing custom parameters​

If you need to pass custom parameters, please use:

val customParameters = HashMap<String, Any>()
customParameters["isVIP"] = 1
TapResearch.showSurveyForPlacement(
    placementTag = "my-placement-tag",
    surveyId = survey.surveyId,  // from your TRSurvey object
    customParameters = customParameters,
    contentListener = object : TRContentCallback {
        override fun onTapResearchContentShown(placementTag: String) {
            // survey is being shown
        }

        override fun onTapResearchContentDismissed(placementTag: String) {
            // survey has been dismissed
        }
    },
    errorListener = object : TRErrorCallback {
        override fun onTapResearchDidError(trError: TRError) {
            // rare error occurred while showing the survey
        }
    }
)