Flutter

What you'll do

1. Install the SDK
2. Set up callbacks
3. Initialize the SDK
4. Display a placement

Later sections cover user attributes, the user identifier, placement details, and more.

Github

The TapResearch flutter plugin with an example app is available on github: https://github.com/TapResearch/tapresearch_flutter_plugin/

Installation

Add the tapresearch_flutter_plugin to your pubspec.yaml file:

dependencies:
  tapresearch_flutter_plugin: ^3.7.0--rc1 # Use the latest version

Or run the following command:

flutter pub add tapresearch_flutter_plugin

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.

Callbacks

The SDK uses callbacks to notify your app of certain events. You should implement these interfaces and provide them to the SDK.

SDK Ready Callback

This function will be called when the SDK is ready to show content.

class MySdkReadyCallback implements TRSdkReadyCallback {
  @override
  void onTapResearchSdkReady() {
    print("TapResearch SDK is ready");
  }
}

Rewards Callback

The SDK will notify you when a user has earned rewards.

class MyRewardCallback implements TRRewardCallback {
  @override
  void onTapResearchDidReceiveRewards(List<TRReward> rewards) {
    for (var reward in rewards) {
      print("Received reward: ${reward.rewardAmount} ${reward.currencyName}");
    }
  }
}

Error Callback

Handle any errors that may occur.

void onError(TRError error) {
  print("TapResearch Error: ${error.description} (Code: ${error.code})");
}

Content Callbacks

Notify your app when content is shown or dismissed.

class MyContentCallback implements TRContentCallback {
  @override
  void onTapResearchContentShown(String placementTag) {
    print("Content shown for $placementTag");
  }

  @override
  void onTapResearchContentDismissed(String placementTag) {
    print("Content dismissed for $placementTag");
  }
}

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,
  );
}

Checking if the SDK is ready

You can check if the SDK is ready using the isReady() method:

void checkSdkReady() async {
  bool isReady = await _plugin.isReady();
  print("SDK Ready: $isReady");
}

Displaying A Placement

You can check whether a placement is available by using canShowContentForPlacement(). It is recommended that you wrap showContentForPlacement calls with this check.

void showPlacement(String placementTag) async {
  bool canShow = await _plugin.canShowContentForPlacement(
    tag: placementTag,
    errorCallback: onError,
  );

  if (canShow) {
    _plugin.showContentForPlacement(
      tag: placementTag,
      contentCallback: MyContentCallback(),
      errorCallback: onError,
    );
  }
}

Passing custom parameters

Custom parameters allow you to receive additional information about the user when they complete a survey.

void showPlacementWithCustomParameters(String placementTag) {
  Map<String, dynamic> customParameters = {
    "custom_param_1": "value1",
    "is_vip": true,
  };

  _plugin.showContentForPlacement(
    tag: placementTag,
    customParameters: customParameters,
    contentCallback: MyContentCallback(),
    errorCallback: onError,
  );
}

Sending User Attributes

User attributes are used to target specific users with surveys.

void sendUserAttributes() {
  Map<String, dynamic> userAttributes = {
    "age": 25,
    "gender": "female",
    "is_vip": true,
  };

  _plugin.sendUserAttributes(
    userAttributes: userAttributes,
    clearPreviousAttributes: false,
    errorCallback: onError,
  );
}

Updating User Identifier

You can set the user identifier at any time.

void updateUserIdentifier(String newUserId) {
  _plugin.setUserIdentifier(
    userIdentifier: newUserId,
    errorCallback: onError,
  );
}

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}");
  }
}

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.

---

Grant Boost

Boosts are temporary reward multipliers that can be granted to users.

class MyGrantBoostListener implements TRGrantBoostResponseListener {
  @override
  void onGrantBoostResponse(TRGrantBoostResponse response) {
    if (response.success == true) {
      print("Boost granted successfully: ${response.boostTag}");
    } else {
      print("Failed to grant boost: ${response.error?.description}");
    }
  }
}

void applyBoost(String boostTag) {
  _plugin.grantBoost(
    boostTag,
    listener: MyGrantBoostListener(),
  );
}

Stay updated: watch TapResearch on GitHub to get notified about new SDK releases.