React Native

Step 1: Setup

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:

"TapResearch", "2.5.0"

$ pod install

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')

Step 2: Initialize

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.

Step 3: Handle 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.

An Event is an object that should be attached to the TRPlacement that will prompt the users with a call to action if you have created one in your supplier dashboard for that specific placement. More on event setup can be found here: Sales & Events.

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

// Register the placement listener
componentDidMount() {
  ...
  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");
  }
}

More About 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 wait for a new TRPlacement object from subsequent placementReady callbacks if you want the user to go back to TapResearch.

Displaying an Event (New!)

When placementReady has been called then you can call displayEvent on the placement you desire:

To display the survey wall, call the TRPlacement.displayEvent method and pass in the placement.

RNTapResearch.displayEvent(this.placement)

To listen to survey wall status, you can add tapResearchSurveyWallOpened and tapResearchSurveyWallDismissed events.

this.tapResearchOnEventOpened = tapResearchEmitter.addListener(
      'tapResearchOnEventOpened',
      placement => {
        console.log('tapResearchOnEventOpened');
        this.onEventOpened(placement);
      },
    );

    this.tapResearchOnEventDismissed = tapResearchEmitter.addListener(
      'tapResearchOnEventDismissed',
      () => {
        console.log('tapResearchOnEventDismissed');
        // Should make a call to fetch placements again
        this.onEventDismissed();
      },
    );

onSurveyButtonPressed = placement => {
    if (typeof placement !== 'undefined' && placement.isSurveyWallAvailable) {
      console.log('Showing the survey wall');
      if (placement.isEventAvailable) {
        RNTapResearch.displayEvent(placement);
        // Alternatively, with passing params
        // RNTapResearch.displayEventWithParams(placement, { 'foos': 'buzz', 'fizz': 'boos' })
      } else {
        RNTapResearch.showSurveyWallWithParams(placement, {
          foos: 'buzz',
          fizz: 'boos',
        });
        // Alternatively, with passing without params
        // RNTapResearch.showSurveyWall(placement);
      }
    } else {
      console.log("The survey wall isn't available", placement);
    }
  };

Step 4: Handle 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 tapResearchOnReceivedReward 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.tapResearchOnReceivedReward = tapResearchEmitter.addListener(
    'tapResearchOnReceivedReward',
    this.onReceivedReward
  )
}ßß

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

Additional callbacks (Optional)

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

tapResearchSurveyWallOpened
tapResearchSurveyWallDismissed

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

Upgrade: to v2.5.0

-initPlacement was deprecated in favour of onPlacementReady callback event.

-Events feature is now available in dashboard to add interstitial functionality to your TRPlacements.

RNTapResearch.onEventOpened
RNTapResearch.onEventDismissed
Placement.isEventAvailable()
Placement.displayEvent()

-Resolved a compliance issue with Google submissions that prevented apps from updating with our 2.4 or lower SDKs.

(Debug) 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.

Done: Going Live

Learn how to take the app live.

Step 1: Setup​

Install the React plugin​

Automatic Installation​

Android​

iOS​

Manual Installation – iOS​

Manual Installation – Android​

Step 2: Initialize​

Step 3: Handle Placements​

More About Placement​

Displaying an Event (New!)​

Step 4: Handle Rewards​

Server to server callback​

In-app callback​

Additional callbacks (Optional)​

Upgrade: to v2.5.0​

(Debug) Troubleshooting​

Survey wall isn't available​

Contact​

Done: Going Live​