@getcello/cello-react-native

React Native wrapper to bridge our iOS and Android SDK

🏠 Website

📚 Developer Docs

• 📂 Homepage
  • Installation
    • Android
      • Android: Automatic linking with React Native v0.59 and below
      • Android: Manual linking with React Native v0.59 and below
      • Android: Setup
      • Android: Permissions
    • IOS
      • iOS: Manual linking with React Native v0.59 and below
      • iOS: Setup
    • Expo
  • Common Methods
  • Usage
  • Troubleshooting
  • Author
  • Show your support
  • License

Installation

npm install @getcello/cello-react-native

or

yarn add @getcello/cello-react-native

Android

If you're using React Native v0.60 or above, the library will be linked automatically without any steps being taken.

Android: Automatic linking with React Native v0.59 and below

react-native link @getcello/cello-react-native

Android: Manual linking with React Native v0.59 and below

• Add below code to android/settings.gradle

include ':cello-react-native'
project(':cello-react-native').projectDir = new File(rootProject.projectDir, '../node_modules/@getcello/cello-react-native/android')

• Then edit android/app/build.gradle, inside dependencies at very bottom add

implementation project(':cello-react-native')

Android: Setup

• Add below lines to android/app/src/main/java/com/YOUR_APP/app/MainApplication.java inside onCreate method, replacing productId and token which can be found in your settings page.

import com.celloreactnative.CelloReactNativeModule; //  <-- Add this line

// ...

@Override
public void onCreate() {
  super.onCreate();
  SoLoader.init(this, /* native exopackage */ false);

  // ...

  CelloReactNativeModule.initialize("productId", "token"); // <-- Add this line

  // ...
}

• Open android/build.gradle and change minSdkVersion to 21, compileSdkVersion to at least 34 and targetSdkVersion to at least 34

buildscript {
    // ...
    ext {
        buildToolsVersion = "29.0.2"
        minSdkVersion = 21 // <-- Here
        compileSdkVersion = 34 // <-- Here
        targetSdkVersion = 34 // <-- Here
    }
    // ...
}

• In android/build.gradle make sure that com.android.tools.build:gradle version is greater than 8.1.1

dependencies {
    classpath("com.android.tools.build:gradle:8.1.1")
    // ...
}

Android: Permissions

You will need to include the INTERNET permission in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

IOS

Cello for iOS requires a minimum iOS version of 15.

cd ios
pod install
cd ..

If you're using React Native v0.60 or above, the library will be linked automatically without any steps being taken.

iOS: Manual linking with React Native v0.59 and below

See How to manually link IOS Cello SDK

iOS: Setup

• Open ios/AppDelegate.m then add below code:

• At the top of file add the following:

#import "AppDelegate.h"
#import <React/RCTBridge.h>
#import <React/RCTBundleURLProvider.h>
#import <React/RCTRootView.h>
// ...
#import <CelloReactNative.h> // <-- Add This

• Inside didFinishLaunchingWithOptions before return YES add, remember to replace productId and token which can be found in your Cello Portal:

  // ...
  self.window.rootViewController = rootViewController;

  [CelloReactNative initialize:for@"productId" with:@"token"]; // <-- Add this (Remember to replace strings with your product id and token)

  return YES;
  }

Expo

If you are using Expo, you can use the built-in plugin.

After installing this package, add the config plugin to the plugins array of your app.json or app.config.js:

{
  "expo": {
    "plugins": ["@getcello/cello-react-native"]
  }
}

The plugin provides props to set environment. Every time you change the props or plugins, you'll need to rebuild (and prebuild) the native app. If no extra properties are added, defaults will be used.

• env (string): Set to your desired environment, such as prod, sandbox. Optional. Defaults to prod.

{
  "expo": {
    "plugins": [
      [
        "@getcello/cello-react-native",
        {
          "env": "sandbox"
        }
      ]
    ]
  }
}

Next, rebuild your app as described in the "Adding custom native code" guide.

Methods

Import

import Cello from '@getcello/cello-react-native';

Cello.initialize()

Initializes the Cello Referral Component in your product

API Styles

The initialize method supports two calling styles:

1. Object-based API (Recommended - New)

import Cello from '@getcello/cello-react-native';

const config = await Cello.initialize({
  productId: 'your-product-id',
  token: 'your-token',
  productUserDetails: {
    firstName: 'John',
    lastName: 'Doe',
    fullName: 'John Doe',
    email: '[email protected]',
  },
});

2. Argument-based API (Legacy - Still Supported)

const config = await Cello.initialize('your-product-id', 'your-token');

InitializeOptions

| Property | Type | Required | Description | | ------------------ | ------------------ | -------- | --------------------------------- | | productId | string | yes | Your product ID from Cello Portal | | token | string | yes | User authentication token | | productUserDetails | ProductUserDetails | no | User details object (see below) |

ProductUserDetails

Optional object with user information:

| Property | Type | Description | | --------- | ------ | -------------------- | | firstName | string | User's first name | | lastName | string | User's last name | | fullName | string | User's full name | | email | string | User's email address |

Returns

Promise<configuration>

Cello.showFab()

Shows the Floating action button or bookmark that launches the Referral Component

Cello.hideFab()

Hides the Floating action button or bookmark that launches the Referral Component

Cello.openWidget()

Opens Referral Component

Cello.hideWidget()

Closes Referral Component

Cello.shutdown()

Closes Referral Component

Cello.getActiveUcc()

A method to get an active ucc and invite link for the currently logged in user.

Returns

{ ucc, link }

Cello.getCampaignConfig()

A method to get the campaign configuration for your product.

Returns

Promise<campaignConfig | null>

Returns a campaign config object with the following properties:

• primaryCurrency (string): Primary currency code
• revenuePercentage (number): Percentage of attributed new revenue that will be paid as a reward
• rewardCap (number): Maximum reward that can be earned per referral
• newSignupBonus (number): Additional reward for signups to encourage more sharing
• newPurchaseBonus (number): Additional reward for purchases to encourage more sharing
• newUserDiscountMonth (number): How long new users get a discount
• newUserDiscountPercentage (number): The discount new users get

Returns null if the SDK is not initialized or if campaign config is not available.

Cello.updateToken(token)

Updates the token and also verifies it.

Options

| Type | Type | Required | | ----- | ------ | -------- | | token | string | yes |

Returns

Promise<configuration>

Cello.changeLanguage(language)

A method to change the language of the Referral component at runtime without re-initialising it.

Options

| Type | Type | Required | | -------- | ------ | -------- | | language | string | yes |

Usage

Check example app

Troubleshooting

• This project uses AndroidX dependencies, but the 'android.useAndroidX' property is not enabled.

  • To enable jetifier, add those two lines to your gradle.properties file:

    android.useAndroidX=true
    android.enableJetifier=true

• When Android app keeps stopping (E/AndroidRuntime: FATAL EXCEPTION: mqt_native_modules)

  • Add those lines to dependencies in ./android/app/build.gradle:

    implementation 'androidx.appcompat:appcompat:1.6.1'

• When tests with Jest fail mentioning "Cannot read property 'TOKEN_ABOUT_TO_EXPIRE' of undefined"

  • Make a jest.mock function with the library:

    // jest/setup.ts
    jest.mock('@getcello/cello-react-native', () => jest.fn());

Author

👤 Cello (https://www.cello.so/)

Show your support

Give a ⭐️ if this project helped you!

📝 License

This project is MIT licensed.

Created with ❤️ by Cello