React Native SDK

Getting Started#

Create an app and grab your API Token.
Add a test device

Install the React plugin#

Run the following command:

$ yarn add react-native-tapresearch

Automatic Installation#

Recommended only for React Native versions below 0.60

Skip this step if you are using React Native version 0.60 and up, in favor of auto-link.

$ react-native link react-native-tapresearch

Android#

In build.gradle of your app, add maven { url "https://artifactory.tools.tapresearch.io/artifactory/tapresearch-android-sdk/" } in the allprojects/repositories section:

allprojects {
  repositories {
    ...

    maven { url "https://artifactory.tools.tapresearch.io/artifactory/tapresearch-android-sdk/" }

    ...
  }
}

iOS#

In project_folder/iOS, update cocoapods:

$ pod install

Please note that the build only works with Xcode 12 and supports iOS 14. If you are using Xcode 11, change node_modules/react-native-tapresearch/react-native-tapresearch.podspec podfile dependency to s.dependency "TapResearch", "2.0.12"

Manual Installation – iOS#

Locate RNTapResearchSDK.xcodeproj — {PROJECT_ROOT}/node_modules/react-native-tapresearch/ios
Open your project and drag RNTapResearchSDK.xcodeproj into the Libraries folder.
Add the libRNTapResearchSDK.a to the Link Binary With Libraries section under the Build Phases tab.

Manual Installation – Android#

Add compile project(':react-native-tapresearch') to the dependencies section in app/build.gradle.
Open MainApplication.java and add new RNTapResearchPackage() to the list found in the getPackages method.
Add the following lines to settings.gradle.

include ':react-native-tapresearch'
project(':react-native-tapresearch').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-tapresearch/android/app')

Initialize TapResearch#

Initialize the TapResearchSDK as early as possible so TapResearch can start getting surveys ready for your users. The initWithApiToken() method only needs to be called once on after the main component has been mounted. It's recommended that you use separate API tokens for iOS and Android so you can track performance metrics separately in the dashboard.

import RNTapResearch from 'react-native-tapresearch';

componentWillMount() {
    RNTapResearch.initWithApiToken(YOUR_API_TOKEN);
}

Next step will be to send a unique user identifier, please note that without a unique identifier the survey wall won't be available.

RNTapResearch.setUniqueUserIdentifier(USER_IDENTIFIER);

Our system only accepts User IDs with ASCII characters. If necessary, you can convert it to BASE64 before sending the User ID to us.

Placements#

A Placement is an object that should be attached to the app's call to action that will direct the users to TapResearch.

To view the available placements or to create a new one, navigate to the app settings in the Supplier Dashboard and copy the placement's identifier.

The Placement is encapsulated in the TRPlacement object which contains metadata and the method to display the survey wall.

Initialize a placement#

It is best to initialize the Placement as late as possible before displaying the placement in the app. For example, you can initialize it in the componentWillUnmount method of the component where the placement will be visible. To initialize the placement, first import the tapResearchEmitter to your component and add a tapResearchOnPlacementReady listener. Second, call the RNTapResearch.initPlacementEvent method like the example below.

...
import { tapResearchEmitter,  PLACEMENT_CODE_SDK_NOT_READY } from 'react-native-tapresearch';

...

// Register the placement listener
componentWillUnmount() {
  ...
  this.tapResearchOnPlacementReady = tapResearchEmitter.addListener(
    'tapResearchOnPlacementReady',
    this.onPlacementReady
  )
  ...
}

// Placement listener
onPlacementReady = (placement) => {
  console.log(placement)
  if (placement.placementCode != PLACEMENT_CODE_SDK_NOT_READY) {
    if (placement.isSurveyWallAvailable) {
      console.log("Survey wall is available");
    } else {
      console.log("Survey wall isn't available");
    }
  } else {
    console.log("The SDK is not ready");
  }
}

...

// Initialize the placement
RNTapResearch.initPlacementEvent(PLACEMENT_IDENTIFIER);

More About Placements#

If initPlacementEvent was called before the SDK initialization was completed, the SDK will return two placements: the first will return a placementCode with a value of PLACEMENT_CODE_SDK_NOT_READY and won't display the survey wall. The second placement response will occur once the SDK is initialized. The placement request will be fired and the callback will be triggered with a live placement.
The survey wall may or may not be available to a specific user. It's important to check survey availability before displaying the call to action.
A placement can only show the survey wall once. After the survey wall is dismissed, you'll have to initialize a new TRPlacement object if you want the user to go back to TapResearch.

####initPlacement (Deprecated) From v2.0.2, initPlacement is deprecated

onPlacementAction() {
  RNTapResearch.initPlacement(PLACEMENT_IDENTIFIER, (placement) => {
    this.placement = placement
    if (placement.isSurveyWallAvailable) {
      // Show the placement
    }
  })
}

Display the survey wall#

To display the survey wall, call the RNTapResearch.showSurveyWall method and pass in the placement.

RNTapResearch.showSurveyWall(this.placement)

To listen to survey wall status, you can add tapResearchSurveyModalOpened and tapResearchSurveyModalDimissed events.

// Notified when the survey wall is visible
this.tapResearchOnSurveyWallOpened = tapResearchEmitter.addListener(
  'tapResearchOnSurveyWallOpened',
  this.onSurveyWallOpened
);

// Notified when the survey wall is dismissed
this.tapResearchOnSurveyWallOpened = tapResearchEmitter.addListener(
  'tapResearchOnSurveyWallOpened',
  this.onSurveyWallDimissed
);

Going Live#

Learn how to take the app live.

Hot Survey#

hasHotSurvey is a placement attribute that indicates a special high-yield survey is available for this user. When this attribute is true, the user should be shown a special call to action to encourage them to take advantage of this opportunity. These special survey opportunities may only be available for a few minutes, so initPlacement should be called whenever the parent view is loaded. If you want to use Hot Surveys, please contact developers@tapresearch.com.

Rewards#

Server to server callback#

To opt in for server to server callbacks, navigate to the Supplier Dashboard. Please visit API docs to learn about callback integration.

In-app callback#

The SDK will check if the user has unredeemed rewards in the following events:

On SDK initialization
When the user exits TapResearch

Pass tapResearchOnReceiveReward and the listener method to tapResearchEmitter to handle new rewards that the player earned in a session.

The reward object information will contain the following fields

Method name	Type	Description
transactionIdentifier()	String	The reward unique identifier
currencyName()	String	The virtual currency name
placementIdentifier()	String	The placement that started the session identifier
rewardAmount()	number	The reward amount in virtual currency. The value will automatically be converted to your virtual currency based on the exchange rate you specified in the app settings.
payoutEvent()	number	The action that the user was rewarded for. 0 - Profile Complete, 3 - Survey Complete.

// Import the TapResearch Event Emitter
import { tapResearchEmitter } from 'react-native-tapresearch';

// Add the listener
componentWillMount() {
  ... // initialize SDK

  this.tapResearchOnReceiveReward = tapResearchEmitter.addListener(
    'tapResearchOnReceivedReward',
    this.onReceiveReward
  )
}

// Implement the callback method.
onReceiveReward = (reward) => {
  // Handle the reward
}

Additional callbacks (Optional)#

Add additional listeners if you want to be notified when the survey modal status has changed or when a survey becomes available. See below for the event names you can subscribe to.

tapResearchSurveyModalOpened
tapResearchSurveyModalDismissed

// Notified when the survey wall is visible
this.tapResearchOnSurveyWallOpened = tapResearchEmitter.addListener(
  'tapResearchOnSurveyWallOpened',
  this.onSurveyWallOpened
);

##Upgrade to v2.0.2 initPlacement was deprecated in favour of initPlacementEvent.

##Upgrade to v2.0.0 On iOS, the package contains the library and there is no need to include it in the actual project. If it is already included (by cocoapods or regular linking), please remove the link to avoid collision.

The following methods and callbacks were removed from the SDK:

RNTapResearch.isSurveyAvailable
RNTapResearch.isSurveyAvailableForIdentifier(identifier)
RNTapResearch.showSurvey()
RNTapResearch.showSurveyWithIdentifier(identifier)

tapResearchOnSurveyAvailable
tapResearchOnSurveyNotAvailable

Test Devices#

Before you are ready to go live, the SDK can only work with a test device. Navigate to your dashboard and click the Add Devices button. Add a device name and a unique user identifier or a Google Advertising ID / Apple IDFA. Now, when you enter our survey flow through your app, you will be able to complete a test survey and receive a test reward when you re-open your app.

Troubleshooting#

Survey wall isn't available#

If placement.isSurveyWallAvailable is false, please reference the Android or iOS integration guides for further steps.

Contact#

Please send all questions, concerns, or bug reports to developers@tapresearch.com.