React Native Setup

📘

This doc supports the React Native SDK through version 2.0.1.
Looking for the newest Nami SDK? Check out the latest docs

Please make sure you have completed the setup of your app on the Nami Control Center for all these steps to be successful.

Adding Nami to your app has a few steps for a basic app.

1. Add the SDK to your project
2. Configure the SDK
3. Show a paywall in your app
4. React to a purchase to grant access to paid content or features

We'll run through each of these below.

Add the SDK to your project

The Nami SDK for React Native is available as a NPM bridge module, that will link in the full native SDK and allow access to various Nami capabilities. The React Native bridge currently supports both Android and iOS. The code for the React Native bridge is also available on our Github.

If you need help setting up your React Native development environment, you can find instructions here:
https://reactnative.dev/docs/environment-setup
.

To add Nami to your React Native project, start by adding the React Native bridge to your project with yarn or npm.

yarn add react-native-nami-sdk

npm install react-native-nami-sdk --save

iOS Projects

📘

React Native for iOS Requirements

The React Native bridge for iOS requires

• CocoaPods 1.9.1+
• React 16.8.0+
• React Native 0.61.0+

After running the yarn install command above, take the following steps to build your app with Nami for Apple devices.

1. Confirm that the minimum version of your iOS project is at least 11.0. You can find this in your Podfile located at ios/Podfile. For a brand new React Native project, the first few lines of your Podfile should look like the example below:

require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'

platform :ios, '11.0'

2. cd ios && pod update
3. You can either run yarn run ios or open your xcworkspace file and build the app in Xcode.

Android Projects

Modify your build.gradle file to work with Nami ML.

1. Edit the build.gradle file in your project, found at android/build.gradle.
2. Add classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.0" to the buildscript > depedencies.
3. Set the minSdkVersion = 21 in buildscript > ext.
4. Add the Nami ML maven repository with this code maven { url("https://nami-android.s3.amazonaws.com/") } to your project under allprojects > repositories.

For a brand new React Native project, your build.gradle file should look like this:

// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
  ext {
    buildToolsVersion = "29.0.2"
    minSdkVersion = 21
    compileSdkVersion = 29
    targetSdkVersion = 29
  }
  repositories {
    google()
    jcenter()
  }
  dependencies {
    classpath("com.android.tools.build:gradle:3.5.3")
    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.0"
    // NOTE: Do not place your application dependencies here; they belong
    // in the individual module build.gradle files
  }
}

allprojects {
  repositories {
    mavenLocal()
    maven {
      // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
      url("$rootDir/../node_modules/react-native/android")
    }
    maven {
      // Android JSC is installed from npm
      url("$rootDir/../node_modules/jsc-android/dist")
    }

    google()
    jcenter()
    maven { url 'https://www.jitpack.io' }
    maven { url("https://nami-android.s3.amazonaws.com/") }
  }
}

Build and run your Android app.

2. Open the project or build.gradle for your app in Android Studio.
3. Allow the gradle sync process to complete.
4. Return to the command line and run the following command:

yarn run android

Configure the SDK

We recommend that you configure the Nami SDK as early in your app's launch as possible. This will ensure the SDK is ready to receive and process purchases.

In React Native apps we recommend placing this code in your App.js file.

First make sure you have imported both the NativeModules and NativeEventEmitter into each of your javascript files where you'll be using the Nami SDK.

import {
  NativeEventEmitter,
  NativeModules
} from 'react-native';

Now to setup Nami, you'll need to call the configure method with App Platform IDs for both Apple and Google.

useEffect(() => {
  var configDict = {
    "appPlatformID-google": "YOUR_PLAY_STORE_APP_PLATFORM_ID",
    "appPlatformID-apple": "YOUR_APP_STORE_APP_PLATFORM_ID",
    "logLevel": "WARN", // optionally set SDK logging level, default:WARN
    "developmentMode": true // turn on features to help with integrating SDK
  };
  NativeModules.NamiBridge.configure(configDict);
}, []);

Nami recommends setting the log level to WARN for apps on the store. INFO may be helpful during development to better understand what is going on. DEBUG level has a lot of information and is likely only helpful to the Nami support team.

Setting up Event Listeners

The React Native bridge for the Nami SDKs uses event emitters and listeners to allow your app to react to various changes that occur.

Examples of these events include:

• The entitlements a user has access to have changed
• The state of purchases on the device has changed
• A sign-in event has occurred
• A Linked Paywall should be displayed
• A paywall is ready for display

👍

Nami Best Practice

Ensure callback listeners are created as early as possible in your app lifecycle and that only 1 listener is created per event.

A list of all events that may be emitted and more details on how event emitters work can be found in Nami Emitters for React Native .

It is important to ensure that your app only registers a single listener per event otherwise you may have the same code executing multiple times. We recommend initializing all listeners in your App.js file with an if statement to check if they have already been created.

Examples are included below in the sections Show a paywall and Grant access to paid app features.

Show a paywall

Now that you have the SDK configured, let's show a paywall in your app. This step requires that you have a Configured paywall in the Nami Control Center and that you have a live Campaign with a User-Initiated Paywall.

We recommend using the preparePaywallForDisplay method, which allows you to optionally wait for images to download and provides helpful errors when the paywall cannot be displayed.

On React Native, this method requires creating an event listener and a callback method to display the paywall when it is ready to be displayed.

import {
  NativeModules,
  NativeEventEmitter
} from 'react-native';

const ScreenName = (props) => {
 ...
 const onPreparePaywallFinished = (result) => {
   if (result.success == true) {
     NativeModules.NamiPaywallManagerBridge.raisePaywall();
   } else {
     console.log("error is " + results.errorMessage );
   }
   
   // remove listener when method completes
   eventEmitter.removeListener('PreparePaywallFinished', onPreparePaywallFinished);
  }
 
  const paywallAction = () => {
    eventEmitter.addListener('PreparePaywallFinished', onPreparePaywallFinished);
    NativeModules.NamiPaywallManagerBridge.preparePaywallForDisplay(true, 2);
  };
}

Consult this guide for more details on Raising a Paywall .

📘

It is important to remember to create a new listener when you want to prepare a paywall for display and then remove it when the method completes.

Grant access to paid app features

Once a user has made a purchase, you'll need to make sure to give them access to the content and features in your app that require a purchase. This is managed on the Nami platform through our entitlement engine.

The first option is to check whether a specific entitlement is active. This is done with the following code.

NativeModules.NamiEntitlementManagerBridge.isEntitlementActive("premium_access", (active) => { 
	if (active) {
    // react to entitlement being active
  }
});

Nami also triggers a callback any time there is a change to the state of an entitlement. In the callback the full list of currently active entitlements is provided. You can use this to store the state of whether a user has access to premium features locally in your app.

As mentioned in the section on Event Listeners above, it is important that any callbacks are created as early in the app launch as possible and that you guard against adding multiple listeners for the same event.

We recommend adding the following code to your App.js to listen for changes to entitlements.

const { NamiEmitter } = NativeModules;
const eventEmitter = new NativeEventEmitter(NamiEmitter);

const onEntitlementsChanged = (event) => {
  // Add code to check for entitlements activating or deactivating features
  console.log("ExampleApp: Data for entitlements changed ", event.activeEntitlements);
}

useEffect(() => {
  if (
    eventEmitter._subscriber._subscriptionsForType.EntitlementsChanged == null
  ) {
    eventEmitter.addListener('EntitlementsChanged', onEntitlementsChanged);
  }
}

That's all the basics to get up and running with Nami using React Native. For more use cases, explore the rest of our docs.