Cello for React Native

The Cello React Native wrapper allows you to use Cello for iOS and Cello for Android in your React Native apps. With a plug-n-play mobile component, your users can easily share their invite link with their friends and network using mobile sharing options convenient for them, receive rewards and get paid out.

Installation

A basic installation takes around 15 minutes, but will take a little longer if you want to customize the way the Cello Referral Component is launched. Compatibility

The Cello React Native wrapper supports React Native 0.59 and above.
Cello for iOS supports iOS 15+.
Cello for Android supports API 21+.

Install Cello

yarn add @getcello/cello-react-native
# or
npm install @getcello/cello-react-native

Android Setup

Automatic Linking (RN v0.60+)

Library is automatically linked after installation.

React Native v0.59 (Automatic Linking)

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

React Native v0.59 (Manual Linking)

android/settings.gradle

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

android/app/build.gradle

dependencies {
  implementation project(':cello-react-native')
}

Android Initialization

Update your MainApplication.java:

import com.celloreactnative.CelloReactNativeModule;

@Override
public void onCreate() {
    super.onCreate();
    SoLoader.init(this, /* native exopackage */ false);
    CelloReactNativeModule.initialize(this, "productId", "token");
}

Also include internet permission in android/app/src/main/AndroidManifest.xml:

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

iOS Setup

Automatic Linking (RN v0.60+)

Library links automatically after pod install.

Manual Linking (RN v0.59)

Open .xcworkspace or .xcodeproj.
Insert the CelloSDK.xcframework into your project (enable “Copy items if needed”).
In target settings, set it to Embed & Sign under Frameworks, Libraries, and Embedded Content.

For additional information on iOS manual linking please refer to the React Native developer docs.

iOS Initialization

In AppDelegate.m, add:

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

Next, in the method didFinishLaunchingWithOptions you’ll need to initialize Cello. Add the snippet below using the productId and token

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

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

  return YES;
  }

Choose an Environment

In your Cello SDK setup, you have the flexibility to select the environment in which your application will run. This feature is especially useful for different stages of development, such as testing in a development or staging environment before going live in production. The available environments are:

prod (Production) (default)
sandbox (Sandbox)

For iOS follow Cello for iOS configurational steps For Android follow Cello for Android configurational steps

Using Cello with Expo

If you are using Expo, you can use the built-in plugin. After installing the @getcello/cello-react-native 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.

Customize the Cello Referral Component

The Cello React Native allows for various levels of customization to better fit into your app’s design and flow. One of the main components you might want to customize is the Referral component

Choose Your Launcher

The library provides two ways to launch the Referral component: Default launcher If you choose to go with the default launcher, you can call the showFab() method from the Cello library to present a Floating Action Button (FAB) within your app. This FAB is pre-styled but may not perfectly match your app’s look and feel.

import Cello from '@getcello/cello-react-native';
Cello.showFab();

Custom launcher If the default launcher does not fit your needs, you can implement your own custom launcher. This could be any UI element like a button, menu item, or even a gesture. To open the Referral component using a custom launcher, you can call Cello.openWidget().

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

const MyButton = () => {
  return <Button onPress={() => Cello.openWidget()}>Open Referral</Button>;
};

React Native API

`Cello.initialize(InitializeOptions): Promise<Configuration>`

Initializes the Cello referral component.

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)
language	string	no	Initial language of the widget
themeMode	string	no	Initial theme mode: `"light"` or `"dark"`

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

Cello.initialize({
  productId: 'your-product-id',
  token: 'your-token',
  productUserDetails: {
    firstName: 'John',
    lastName: 'Doe',
    fullName: 'John Doe',
    email: 'john.doe@example.com',
  },
  language: 'de',
  themeMode: 'light',
});

`Cello.showFab(): void`

Shows the default Cello button that launches the Referral Component

Cello.showFab();

`Cello.hideFab(): void`

Hides the default Cello button that launches the Referral Component

Cello.hideFab();

`Cello.openWidget(): void`

Opens the referral component.

Cello.openWidget();

`Cello.hideWidget(): void`

Hides the referral component.

Cello.hideWidget();

`Cello.getActiveUcc(): Promise<{ ucc: string; inviteLink: string; } | null>`

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

const data = await Cello.getActiveUcc();

`Cello.changeLanguage(langCode: string): void`

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

Cello.changeLanguage('de');

`Cello.setThemeMode(themeMode: string): void`

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

Cello.setThemeMode('dark');

Parameters:

themeMode (string): The theme mode to set. Valid values are "light" or "dark".

`Cello.shutdown(): void`

Shuts down connection to Cello and unmounts the component

Cello.shutdown();

Error Handling

Promise rejection codes

Code	Platform(s)	Trigger	Typical causes
`InitializationError`	iOS & Android	`Cello.initialize` completes with native failure	Invalid/empty product ID or token, network issues, bad environment
`InitializationException`	Android	Unexpected exception inside `Cello.initialize`	Activity finishing, SDK not linked correctly, runtime crash
`ActivityError`	Android	`Cello.initialize` without an active Activity	Initialization triggered too early (e.g. before React root ready)
`TokenUpdateError`	iOS	`Cello.updateToken` failure	Token expired/invalid, network errors
`LanguageChangeError`	iOS	`Cello.changeLanguage` failure	Unsupported language code, network errors
`ThemeModeChangeError`	iOS	`Cello.setThemeMode` failure	Invalid theme mode value, network errors
`UnavailableError`	iOS	Feature requires iOS 14+	Device running < iOS 14 when calling token, language, or theme updates
`NO_ACTIVE_UCC`	iOS	`Cello.getActiveUcc` with no active referral	User has not generated an invite yet
`UCC_ERROR`	Android	`Cello.getActiveUcc` threw	SDK not initialized, network or serialization errors
`CAMPAIGN_CONFIG_ERROR`	Android	`Cello.getCampaignConfig` threw	SDK not initialized, configuration not ready
`LINKING_ERROR`	JavaScript	Module not linked	Pod install missing, app not rebuilt, using Expo Go

Tip: The React Native bridge rejects promises with the objects above. Inspect error.code, error.message, and (on iOS) error.nativeStackIOS for extra context.

Common error scenarios

1. Initialization promise rejected

Symptoms: InitializationError or InitializationException in the catch block. Fix: Validate credentials, confirm network connectivity, and ensure you selected the right environment (prod vs sandbox). Compare native logs with the iOS and Android error references for detailed native codes.

2. Module not linked (`LINKING_ERROR`)

Symptoms: Error thrown immediately when importing @getcello/cello-react-native. Fix: Run pod install inside ios, rebuild the app, and ensure you are not running inside Expo Go. For older RN versions (0.59), double-check manual linking steps.

3. UI calls before initialization finishes

Calling Cello.showFab(), Cello.openWidget(), or similar before the SDK is ready triggers native console warnings such as "Error: showFab() called before initialization.". Track initialization state in JavaScript and gate UI interactions until Cello.initialize resolves.

4. Platform feature limitations

Cello.changeLanguage and Cello.setThemeMode require iOS 14+. On older devices the bridge rejects with UnavailableError. Guard these calls with a platform/version check.

Error handling best practices

1. Wrap initialization in try/catch:

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

async function bootstrapCello() {
  try {
    if (!productId.trim() || !token.trim()) {
      throw new Error('Missing credentials');
    }

    const config = await Cello.initialize({
      productId,
      token,
      productUserDetails,
    });

    setCelloReady(true);
    console.log('[Cello] Initialized', config);
  } catch (error: any) {
    console.warn('[Cello] Initialization failed', error);
    Alert.alert(
      'Referrals unavailable',
      'Please check your connection and try again.'
    );
  }
}

2. Delay UI interactions: Only call Cello.showFab() or Cello.openWidget() after a successful initialization. Keep a dedicated isCelloReady state flag in your components. 3. Retry on transient errors: For recoverable failures (network timeouts, InitializationError), schedule a retry with exponential or linear backoff. Limit retries to avoid looping endlessly. 4. Log error details: Capture error.code, error.message, and relevant native stack traces in your logging/monitoring solution to help support diagnose issues quickly.

SDKs

Client-Side SDKs

Mobile SDKs

Cello for React Native

Installation

Install Cello

Android Setup

Automatic Linking (RN v0.60+)

React Native v0.59 (Automatic Linking)

React Native v0.59 (Manual Linking)

Android Initialization

iOS Setup

Automatic Linking (RN v0.60+)

Manual Linking (RN v0.59)

iOS Initialization

Choose an Environment

Using Cello with Expo

Customize the Cello Referral Component

Choose Your Launcher

React Native API

`Cello.initialize(InitializeOptions): Promise<Configuration>`

InitializeOptions

ProductUserDetails

`Cello.showFab(): void`

`Cello.hideFab(): void`

`Cello.openWidget(): void`

`Cello.hideWidget(): void`

`Cello.getActiveUcc(): Promise<{ ucc: string; inviteLink: string; } | null>`

`Cello.changeLanguage(langCode: string): void`

`Cello.setThemeMode(themeMode: string): void`

`Cello.shutdown(): void`

Error Handling

Promise rejection codes

Common error scenarios

1. Initialization promise rejected

2. Module not linked (`LINKING_ERROR`)

3. UI calls before initialization finishes

4. Platform feature limitations

Error handling best practices

SDKs

Client-Side SDKs

Mobile SDKs

​Installation

​Install Cello

​Android Setup

​Automatic Linking (RN v0.60+)

​React Native v0.59 (Automatic Linking)

​React Native v0.59 (Manual Linking)

​Android Initialization

​iOS Setup

​Automatic Linking (RN v0.60+)

​Manual Linking (RN v0.59)

​iOS Initialization

​Choose an Environment

​Using Cello with Expo

​Customize the Cello Referral Component

​Choose Your Launcher

​React Native API

​Cello.initialize(InitializeOptions): Promise<Configuration>

​InitializeOptions

​ProductUserDetails

​Cello.showFab(): void

​Cello.hideFab(): void

​Cello.openWidget(): void

​Cello.hideWidget(): void

​Cello.getActiveUcc(): Promise<{ ucc: string; inviteLink: string; } | null>

​Cello.changeLanguage(langCode: string): void

​Cello.setThemeMode(themeMode: string): void

​Cello.shutdown(): void

​Error Handling

​Promise rejection codes

​Common error scenarios

​1. Initialization promise rejected

​2. Module not linked (LINKING_ERROR)

​3. UI calls before initialization finishes

​4. Platform feature limitations

​Error handling best practices

Installation

Install Cello

Android Setup

Automatic Linking (RN v0.60+)

React Native v0.59 (Automatic Linking)

React Native v0.59 (Manual Linking)

Android Initialization

iOS Setup

Automatic Linking (RN v0.60+)

Manual Linking (RN v0.59)

iOS Initialization

Choose an Environment

Using Cello with Expo

Customize the Cello Referral Component

Choose Your Launcher

React Native API

`Cello.initialize(InitializeOptions): Promise<Configuration>`

InitializeOptions

ProductUserDetails

`Cello.showFab(): void`

`Cello.hideFab(): void`

`Cello.openWidget(): void`

`Cello.hideWidget(): void`

`Cello.getActiveUcc(): Promise<{ ucc: string; inviteLink: string; } | null>`

`Cello.changeLanguage(langCode: string): void`

`Cello.setThemeMode(themeMode: string): void`

`Cello.shutdown(): void`

Error Handling

Promise rejection codes

Common error scenarios

1. Initialization promise rejected

2. Module not linked (`LINKING_ERROR`)

3. UI calls before initialization finishes

4. Platform feature limitations

Error handling best practices