Android 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

• Integration guide: See the Android SDK documentation
• Example apps: Available on GitHub

Before you begin

• You must be on SDK v3.4.0+ 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

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:

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"
  val category: String? = null, // The survey's category, if it has one

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

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

The code below demonstrates how to:

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

Key points:

• Fetch surveys only after the SDK Ready event
• Use hasSurveysForPlacement(placementTag, errorListener) if you only need to know whether any surveys are available
• Render the TRSurvey objects in your UI (see handleMySurveys function)
• Set the surveys refreshed listener to get updates when surveys change

Warning

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

Kotlin

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") { error -> handleMyError(error) }
        handleMySurveys(surveys) // your surveys handler; handle null or empty list

        // Set your surveys refreshed listener
        TapResearch.setSurveysRefreshedListener(object : TRSurveysRefreshedListener {
            override fun onSurveysRefreshedForPlacement(placementTag: String) {
                if (placementTag == "my-placement-tag") {
                    val updatedSurveys = TapResearch.getSurveysForPlacement(placementTag) { error -> handleMyError(error) }
                    handleMySurveys(updatedSurveys) // your surveys handler; handle null or empty list
                }
            }
        })
    },
    rewardCallback = { rewards -> handleMyRewards(rewards) },
    initOptions = null,
    qqDataCallback = null,
)

Java

TapResearch.INSTANCE.initialize(
    "my-api-token",
    "my-user-identifier",
    MainActivity.this, // context
    this::handleMyRewards,
    this::handleMyError,

    // SDK ready handler
    () -> {
        Log.d(LOG_TAG, "SDK Ready");

        // Surveys can be fetched anytime after SDK Ready
        List<TRSurvey> surveys = TapResearch.INSTANCE.getSurveysForPlacement("my-placement-tag", this::handleMyError);
        handleMySurveys(surveys); // your surveys handler; handle null or empty list

        // Set your surveys refreshed listener
        TapResearch.INSTANCE.setSurveysRefreshedListener(placementTag -> {
            if (placementTag.equals("my-placement-tag")) {
                List<TRSurvey> updatedSurveys = TapResearch.INSTANCE.getSurveysForPlacement(placementTag, this::handleMyError);
                handleMySurveys(updatedSurveys);
            }
        });
    },
    this::handleQuickQuestion,
    null //tapInitOptions
);

Showing a survey

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

Kotlin

val surveyId = survey.surveyId ?: return // from TRSurvey object

TapResearch.showSurveyForPlacement(
    placementTag = "my-placement-tag",
    surveyId = surveyId,
    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
        }
    }
)

Java

String surveyId = survey.getSurveyId(); // from TRSurvey object; check for null

TapResearch.INSTANCE.showSurveyForPlacement(
    "my-placement-tag",
    surveyId,
    null,  // custom parameters
    new TRContentCallback() {

        @Override
        public void onTapResearchContentShown(String placementTag) {
            // survey is being shown
        }

        @Override
        public void onTapResearchContentDismissed(String placementTag) {
            // survey was dismissed
        }
    },
    new TRErrorCallback() {
        @Override
        public void onTapResearchDidError(TRError trError) {
            // a rare error occurred while showing the survey
        }
    }
);

Passing custom parameters

If you need to pass custom parameters, please use:

Kotlin

val customParameters = HashMap<String, Any>()
customParameters["isVIP"] = 1
TapResearch.showSurveyForPlacement(
    placementTag = "my-placement-tag",
    surveyId = surveyId,  // the non-null 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
        }
    }
)

Java

HashMap<String, Object> customParameters = new HashMap<>();
customParameters.put("isVIP", 1);
TapResearch.INSTANCE.showSurveyForPlacement(
        "my-placement-tag",
        survey.getSurveyId(),  // from your TRSurvey object; check for null
        customParameters,
        new TRContentCallback() {

            @Override
            public void onTapResearchContentShown(String placementTag) {
                // survey is being shown
            }

            @Override
            public void onTapResearchContentDismissed(String placementTag) {
                // survey has been dismissed
            }
        },
        new TRErrorCallback() {

            @Override
            public void onTapResearchDidError(TRError trError) {
                // a rare error occurred while showing the survey
            }
        }
);