cello_sdk #

Flutter plugin that bridges the native Cello Android and iOS SDKs, mirroring the React Native wrapper API (initialize, FAB helpers, widget controls, lifecycle methods, UCC/config queries, and token lifecycle events).

Features #

• Parity with @getcello/cello-react-native JavaScript API surface.
• Kotlin + Swift implementations that wrap the native SDKs (so.cello.android:cello-sdk:0.12.0 / CelloSDK ~> 0.12.0).
• MethodChannel + EventChannel bridge with strongly-typed Dart models.
• Token lifecycle events exposed as a broadcast Stream<CelloTokenEvent>.
• Example Flutter app showing initialization, FAB/widget control, and event handling.

Requirements #

Installation #

Add the dependency to your pubspec.yaml:

dependencies:
  cello_sdk: ^0.0.1

Run flutter pub get.

Android setup #

The plugin automatically pulls the native dependency. Ensure your app-level build.gradle (or Kotlin DSL equivalent) includes:

android {
  compileSdk 34
  defaultConfig {
    minSdk 21
  }
}

repositories {
  google()
  mavenCentral()
}

If you rely on ProGuard/R8, keep the shipped consumer-rules.pro or add custom rules for your app if obfuscation removes Cello classes.

iOS setup #

1. Open ios/Podfile and ensure your platform target is at least 15.0.
2. From the ios/ directory run pod install after adding the plugin.
3. The plugin ships a privacy manifest (Resources/PrivacyInfo.xcprivacy) so no extra configuration is required beyond standard Flutter setup.

Usage #

import 'package:cello_sdk/cello_sdk.dart';

Future<void> bootstrapCello() async {
  final config = await Cello.initialize(
    CelloInitializeOptions(
      productId: 'YOUR_PRODUCT_ID',
      token: 'signed-user-token',
      environment: 'sandbox',
      language: 'en',
      userDetails: ProductUserDetails(
        firstName: 'Ada',
        lastName: 'Lovelace',
        email: '[email protected]',
      ),
    ),
  );

  // Optionally inspect the configuration object the SDK returned.
  debugPrint('Cello configuration: \${config.rawResponse}');

  // Show the default FAB launcher provided by the SDK.
  await Cello.showFab();

  // Listen for token lifecycle events.
  Cello.tokenEvents.listen((event) {
    switch (event.type) {
      case CelloTokenEventType.tokenAboutToExpire:
        // Refresh token and call Cello.updateToken(...)
        break;
      case CelloTokenEventType.tokenHasExpired:
        break;
    }
  });
}

API surface #

Token events #

Events are delivered through an EventChannel to match React Native’s CelloEvents. Each event is surfaced as a CelloTokenEvent with an enum (tokenAboutToExpire / tokenHasExpired), timestamp, and optional payload map. Subscribe once during app startup and keep the subscription for the app’s lifetime.

Example app #

The example/ directory contains a runnable Flutter application that:

• Accepts runtime product ID, token, environment, language, and optional user profile data.
• Calls Cello.initialize, toggles FAB/widget visibility, and performs shutdown.
• Streams token events into a log panel and demonstrates getActiveUcc / getCampaignConfig.

Run it with:

cd example
flutter run # specify -d <device> for Android/iOS

Provide valid credentials in the UI before tapping Initialize & Show FAB.

Development & testing #

• Run flutter format lib test example/lib before committing changes.
• Run flutter analyze and flutter test from the repo root.
• Manual validation: launch the example app on both Android and iOS with test credentials to confirm FAB/widget controls, event delivery, token refresh, and shutdown work as expected.

Parity with React Native wrapper #

• The Dart API mirrors the RN TypeScript API surface and naming.
• Native integrations use the same SDK versions (0.12.0).
• Token event channel names (tokenAboutToExpire / tokenHasExpired) and method argument shapes match the RN bridges, ensuring drop-in equivalence for developers migrating from React Native.

For additional SDK details refer to the official Cello documentation.