@getcello/cello-react-native

中文文档
0.17.0发布于 2026/11/12MITTypeScriptESM + CJS零依赖近 30 天下载 5.3万

React Native wrapper to bridge iOS and Android SDK

原始使用文档
文档目录33 节
  1. 🏠 Website
  2. 📚 Developer Docs
  3. Installation
  4. Android
  5. IOS
  6. Expo
  7. Methods
  8. Import
  9. import Cello from '@getcello/cello-react-native';
  10. Cello.initialize()
  11. API Styles
  12. InitializeOptions
  13. ProductUserDetails
  14. Returns
  15. Cello.showFab()
  16. Cello.hideFab()
  17. Cello.openWidget()
  18. Cello.hideWidget()
  19. Cello.shutdown()
  20. Cello.getActiveUcc()
  21. Returns
  22. Cello.getCampaignConfig()
  23. Returns
  24. Cello.updateToken(token)
  25. Options
  26. Returns
  27. Cello.changeLanguage(language)
  28. Options
  29. Usage
  30. Troubleshooting
  31. Author
  32. Show your support
  33. 📝 License

@getcello/cello-react-native

React Native wrapper to bridge our iOS and Android SDK

🏠 Website

📚 Developer Docs



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.

The iOS SDK (CelloSDK.xcframework) ships inside this package, so there is nothing to add to your Podfile. Don't also add CelloSDK through the Podfile or Swift Package Manager: the app would get two copies of the framework. With a pod 'CelloSDK' line, pod install stops with target has frameworks with conflicting names: cellosdk.xcframework; remove that line.

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:

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

PropertyTypeRequiredDescription
productIdstringyesYour product ID from Cello Portal
tokenstringyesUser authentication token
productUserDetailsProductUserDetailsnoUser details object (see below)

ProductUserDetails

Optional object with user information:

PropertyTypeDescription
firstNamestringUser's first name
lastNamestringUser's last name
fullNamestringUser's full name
emailstringUser'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

TypeTypeRequired
tokenstringyes

Returns

Promise<configuration>


Cello.changeLanguage(language)

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

Options

TypeTypeRequired
languagestringyes

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

版本与发布记录

@getcello/cello-react-native 共发布 52 个版本,首次发布于 2024/04/27;过去 12 个月发布了 11 个版本。

版本发布日期距今
0.17.0latest2026/11/124 天前
0.17.0-rc.0rc2026/11/124 天前
0.16.02026/10/061 个月前
0.15.12026/09/301 个月前
0.15.02026/09/092 个月前
0.15.0-rc.02026/09/092 个月前

关于 @getcello/cello-react-native 的常见问题

@getcello/cello-react-native 是什么?

React Native wrapper to bridge iOS and Android SDK

如何安装 @getcello/cello-react-native?

在项目目录运行 npm install @getcello/cello-react-native,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(*)、react-native(*)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@getcello/cello-react-native 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@getcello/cello-react-native 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@getcello/cello-react-native 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >= 18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@getcello/cello-react-native 可以商用吗?

@getcello/cello-react-native 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@getcello/cello-react-native 的下载量有多少?

根据 npm 官方下载统计,@getcello/cello-react-native 在 2026/10/17 – 2026/11/15 这 30 天内被下载 52,582 次,日均约 1,753 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@getcello/cello-react-native 还在维护吗?

最新版本 0.17.0 发布于 2026/11/12(4 天前);至今共发布 52 个版本,其中过去 12 个月发布了 11 个;首次发布于 2024/04/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。