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: