Flutter Native Survey Tiles

Installation

• Integration guide: See the Flutter SDK documentation
• Sample Survey Wall Preview app with custom tiles: Available on GitHub

Before You Begin

• 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 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!

Integration

Test Mode

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

The code below demonstrates how to:

• Fetch surveys after SDK initialization
• 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 SurveyWallPreviewScreen in the Sample App
• Required: 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.

Initialization

Initialize the TapResearch SDK as early as possible. It is required to use different API tokens for iOS and Android.

tip

The user identifier passed through initialization must be unique per user! Only initialize once you are able to provide a unique identifier. Re-using the same user identifier is not supported and will prevent your users from accessing our service.

import 'package:tapresearch_flutter_plugin/tapresearch_flutter_plugin.dart';

final _plugin = TapresearchFlutterPlugin();

void initTapResearch() {
  final String apiKey = Platform.isAndroid ? "YOUR_ANDROID_API_KEY" : "YOUR_IOS_API_KEY";
  final String userIdentifier = "YOUR_UNIQUE_USER_ID";

  _plugin.initialize(
    apiKey: apiKey,
    userIdentifier: userIdentifier,
    rewardCallback: MyRewardCallback(),
    sdkReadyCallback: MySdkReadyCallback(),
    errorCallback: onError,
  );
}

Set the Surveys Refreshed Listener

Implement TRSurveysRefreshedListener to be notified when surveys are refreshed and available for a placement.

When surveys are refreshed, we recommend calling getSurveysForPlacement() so you can re-render your custom UI, as survey tile values may have changed. It could also be a good time to call getPlacementDetails() because the placementDetails.contentType may have changed. Possible values could be profiler or survey_wall_preview or another string value.

class MySurveysRefreshedListener implements TRSurveysRefreshedListener {
  @override
  void onSurveysRefreshedForPlacement(String placementTag) {
    print("Surveys refreshed for $placementTag");
    /* This is a good time to call getSurveysForPlacement() to re-render your SWP screen
       and / or 
       getPlacementDetails() where the returned placementDetails.contentType 
       can be 'profiler' or 'survey_wall_preview' or another string value
     */
  }
}

Provide the listener to the SDK:

_plugin.setSurveysRefreshedListener(MySurveysRefreshedListener());

Get Surveys for Placement

Use getSurveysForPlacement() to fetch the list of available surveys for a placement tag.

void fetchSurveys(String placementTag) async {
  List<TRSurvey>? surveys = await _plugin.getSurveysForPlacement(placementTag);
  
  if (surveys != null && surveys.isNotEmpty) {
    for (var survey in surveys) {
      print("Available Survey: ${survey.surveyId} - Reward: ${survey.rewardAmount}");
    }
  }
}

Show Survey

When a user selects a survey from your custom UI, use showSurveyForPlacement() to open it.

void openSurvey(String placementTag, String surveyId) {
  _plugin.showSurveyForPlacement(
    tag: placementTag,
    surveyIdentifier: surveyId,
    contentCallback: MyContentCallback(),
    errorCallback: onError,
  );
}

TRSurvey Class

Property	Type	Description
surveyId	String?	Unique identifier for the survey.
lengthInMinutes	int?	Estimated time to complete in minutes.
rewardAmount	double?	The reward amount for completion.
currencyName	String?	The name of the currency.
isSale	bool?	Indicates if a sale is active for this survey.
isHotTile	bool?	Indicates if this is a high-priority survey.

---

Getting Placement Details

Note!

Placement details can change as our SDK refreshes placements in the background, so it is not recommended to store or cache these values. Instead, refetch the details each time you need to use them, e.g. to display something in your UI.

Get placement details by calling getPlacementDetails(placementTag, errorListener).

void getPlacementInfo(String placementTag) async {
  TRPlacementDetails? details = await _plugin.getPlacementDetails(
    placementTag,
    errorListener: onError,
  );
  
  if (details != null) {
    print("Placement Name: ${details.name}");
    print("Is Sale Active: ${details.isSale}");
  }
}

See Set the Surveys Refreshed Listener

Example Survey Wall Preview screen with custom tiles can be seen at (SurveyWallPreviewScreen class): https://github.com/TapResearch/tapresearch_flutter_plugin/blob/master/example/lib/main.dart

TRPlacementDetails Class

TRPlacementDetails contains the following properties:

Property	Type	Description
name	String?	The name of the placement.
contentType	String?	The type of content associated with the placement.
currencyName	String?	The name of the currency rewarded by this placement.
isSale	bool?	Indicates if there is an active sale.
saleType	String?	The category or type of the active sale.
saleEndDate	String?	When the sale expires (UTC date string).
saleMultiplier	double?	The reward multiplier during a sale.
saleDisplayName	String?	The display name for the sale.
saleTag	String?	A tag associated with the sale.
bonusBarProgress	TRBonusBarProgress?	The user's progress toward a bonus.

TRBonusBarProgress Class

Property	Type	Description
isActive	bool?	Indicates if the bonus bar is currently active.
currentCompletes	int?	The number of survey completions achieved toward the bonus.
bonusWindowEndAt	String?	When the bonus window expires (UTC date string).
bonusTiers	List<TRBonusTier>?	A list of tiers available in the progress bar.
error	TRError?	Error information if the progress could not be retrieved.

TRBonusTier Class

Property	Type	Description
tierNumber	int?	The sequence number of the tier.
completesNeeded	int?	Number of completions required to reach this tier.
rewardAmount	double?	The reward granted upon completing this tier.
status	String?	The current status of the tier.

---