React Native SDK
#
Getting Started- Create an app and grab your API Token.
- Add a test device
#
Install the React pluginRun the following command:
$ yarn add react-native-tapresearch
#
Automatic InstallationRecommended 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
#
AndroidIn build.gradle of your app, add maven { url "https://artifactory.tools.tapresearch.io/artifactory/tapresearch-android-sdk/" }
in the allprojects/repositories
section:
#
iOSIn 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 addnew RNTapResearchPackage()
to the list found in thegetPackages
method. - Add the following lines to settings.gradle.
#
Initialize TapResearchInitialize 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.
Next step will be to send a unique user identifier, please note that without a unique identifier the survey wall won't be available.
Our system only accepts User IDs with ASCII characters. If necessary, you can convert it to BASE64 before sending the User ID to us.
#
PlacementsA 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 placementIt 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.
#
More About PlacementsIf
initPlacementEvent
was called before the SDK initialization was completed, the SDK will return two placements: the first will return aplacementCode
with a value ofPLACEMENT_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
#
Display the survey wallTo display the survey wall, call the RNTapResearch.showSurveyWall
method and pass in the placement.
To listen to survey wall status, you can add tapResearchSurveyModalOpened
and tapResearchSurveyModalDimissed
events.
#
Going LiveLearn how to take the app live.
#
Hot SurveyhasHotSurvey
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 callbackTo opt in for server to server callbacks, navigate to the Supplier Dashboard. Please visit API docs to learn about callback integration.
#
In-app callbackThe 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. |
#
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
##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:
#
Test DevicesBefore 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 availableIf placement.isSurveyWallAvailable
is false, please reference the Android or iOS integration guides for further steps.
#
ContactPlease send all questions, concerns, or bug reports to developers@tapresearch.com.