TapResearch React Native Integration Guide

Getting Started

Install the React plugin

Run the following command:

$ npm i react-native-tapresearch -S

$ 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/" }

      ...
    }
  }

Manual Installation - iOS

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

Manual Installation - Android

  1. Add compile project(':react-native-tapresearch') to the dependencies section in app/build.gradle.
  2. Open MainApplication.java and add new RNTapResearchPackage() to the list found in the getPackages method.
  3. 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);

Placements

A placement is the allocated section in your application where you want to provide access to TapResearch's survey wall, like an action button or a list item. To create a placement, navigate to the app settings in the supplier dashboard click settings and add the placement. The placement is encapsulated by the TRPlacement object which contains the placement metadata and the method to display the survey wall.

Initialize a placement

To initialize a placement, it is best practice to call the SDK 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 demonstrated 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");
    }
  }

  ...

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

The survey wall may or may not be available to a specific user and it's important to check survey availability before displaying the placement.

Also please note that if the placement request was fired before the SDK was ready the tapResearchOnPlacementReady will be called twice. The first time placement.placementCode will return PLACEMENT_CODE_SDK_NOT_READY indicating that the request was fired before the SDK was ready, the second call will return the latest placement from the server

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)

Please Note: A placement can only show the survey wall one time. Once the survey wall is dismissed, you'll have to initialize a new TRPlacement object if you wish to keep the placement visible in the app.

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 Survey please contact developers@tapresearch.comdevelopers@tapresearch.com.

Reward notifications

Depending on your preferences the rewards notification will be posted to a url or will trigger an in-game game callback. Please follow the instructions below for server postback or in-game callback implementations

Server to server postback

To opt in for server to server postbacks, navigate to the supplier dashboard. Please visit API docs to learn about postbacks integration.

In-Game callback

Add a reward listener so we can notify you when a user completes a survey. The quantity value will automatically be converted to your virtual currency based on the exchange rate you specified in your app settings. It is important to note that this method may be called back to back if the player completed multiple surveys in one session.


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

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

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

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

Additional callbacks (Optional)

Add additional listeners if you want to be notified when the survey modal status has changed or a 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

Android build failed due to a manifest conflict

If The android build failed because the android:allowBackup attribute is conflicting add tools:replace="allowBackup" to the Application section

Contact

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