React Native SDK Legacy
Integrate Ribbon in your React Native app using the Ribbon React Native SDK
Getting started
Requirements
Before you start, make sure that:
- You have access to your team's Ribbon account, and can find your team's unique Ribbon ID in Integration > React Native SDK in your Ribbon account.
- You have access to your applications React Native codebase so that you can install the Ribbon React Native SDK.
Install the Ribbon React Native SDK with npm/Yarn
Install the Ribbon React Native SDK through NPM or Yarn with the following command:
npm install --save @ribbontechnologies/react-native-ribbon
yarn add @ribbontechnologies/react-native-ribbon
iOS Setup
Run npx pod-install
to setup the required dependencies for the iOS side of the project, this should install the RibbonKit
framework.
Once this is done, you can run npx react-native run-ios
to launch the iOS app.
Minimum supported version
Although the minimum supported iOS version for the SDK is 11, which makes it possible to integrate in all React Native projects, the actual SDK features are only available for iOS 14.0 and up.
The platform version check is done at runtime and calling Ribbon functions for versions lower than that won't do anything.
Android setup
Using React Native v0.60 and above
If you're using React Native v0.60 or above, the library will be linked automatically
Automatic linking with React Native v0.59
To automatically link the Ribbon React Native wrapper in v0.59 of React Native run the following command:
react-native link @ribbontechnologies/react-native-ribbon
Ribbon SDK Configuration
Now in your application you should be able to run configure using your Ribbon ID
import Ribbon from '@ribbontechnologies/react-native-ribbon'
// ...
Ribbon.configure('RIBBON_ID');
Replace RIBBON_ID
with your own Ribbon ID, which you can find in Integration > React Native SDK in your Ribbon account.
Code triggers
After installing the Ribbon SDK you can now use triggers to launch a study. A trigger is the action that prompts the Ribbon widget to be displayed to a user if they are eligible for the study. For React Native these are always declared in your application's code.
To create a trigger you need to invoke it in your code. Once successfully triggered it will become selectable as part of study creation for React Native. If this is the first trigger that was added to your account, then invoking it successfully for the first time will allow the iOS/Android platform to be selectable in study creation.
There a couple of ways to add triggers to your application. The easiest way to invoke a trigger and show a study is by calling:
Ribbon.triggerAndShow("NAME_OF_YOUR_TRIGGER")
To have greater control over when and how studies are presented, you can trigger a study using the trigger(:completion:)
method (or its async equivalent), and determine whether or not to show it if no RibbonError
has been provided in the completion closure (or thrown in the async version).
To then show the study, you can simply call the show()
method.
Ribbon.trigger("NAME_OF_YOUR_TRIGGER").then(() => {
Ribbon.show()
}).catch((error) => {
// handle error
})
}
To verify that a trigger is being invoked in your application you can view the latest triggered events on the Debugger tab on the Integrations page.
Identify users
You are able to identify your users in the Ribbon platform through assigning identifiers within your platform to ours. This is done through the integration, calling our identify method with the id - you are then able to see this identifier associated with each participant under the Participants page.
To identify who a current user is, simply set the identify method and pass along a unique User ID:
Ribbon.setIdentity("user-1234567890")
You can clear the identity as well as any attributes set by:
Ribbon.clearSession()
User attributes
The Ribbon attribute method lets you associate attributes with a participant. It can be used to filter which participants you target with your studies more narrowly, and to tie information to specific participants. The data in your attribute method is sent to Ribbon whenever a Ribbon trigger is called.
What is a user attribute?
User attributes are used to track facts about your users. For example, you can track what plan a user is on. This is different from triggers, which track actions, and are used to decide when a study should be initiated.
Here's a list of some common user attributes researchers set up on Ribbon:
- Number of products purchased
- Total order value
- Subscription plan
Here's an example of how to use user attributes to track facts about users. Let's assume your product is an e-commerce website. In this case, you can use user attributes to track how many products a customer has purchased. To track the number of products a customer has purchased, you could set the attribute:
Ribbon.setAttributes({"products-purchased": 48})
In this scenario, if you wanted to target a study on Ribbon to users with more than 30 products purchased, you would then set your attribute filter when you launch your study to only target users with 30 or more products purchased.
Creating attributes
Attributes are automatically created in your workspace when they are sent through your Ribbon integration. You don't need to manually create each attribute from the Ribbon dashboard. To view your active attributes go to Events > Attributes.
How to format your attributes
The attribute data is sent in the form of key-value pairs, and can be in the form of numbers, booleans and strings only. You can set a single attribute as such:
Ribbon.setAttributes({"key1": "value1"})
You can also set multiple attributes:
Ribbon.setAttributes({"key3": "value3", "key4": 1, "key5": true})
You can remove one or several of the attributes:
Ribbon.removeAttributes(["key1", "key2"])
You can also remove all attributes:
Ribbon.removeAllAttributes()
Filter participants using attributes
When you start a new study, you can then choose to only display the Ribbon widget to users that have certain attributes set to specific values:
Updated 5 months ago