cello_sdk 0.0.1

Flutter plugin wrapper for the Cello iOS and Android SDKs.

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

Platform	Minimum	Notes
Flutter	3.3.0+ (Dart 3)	Tested with Flutter 3.38.0.
Android	minSdk 21, compileSdk 34	Requires Maven Central access for the Cello SDK.
iOS	iOS 15.0+, Xcode 15+	use_frameworks! supported; run pod install after adding the plugin.

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: '[e-mail]',
      ),
    ),
  );

  // 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

Dart method	Description
Cello.initialize(options)	Initializes the SDK. Must be called once with a foreground Activity (Android) / on the main thread (iOS). Returns CelloConfiguration.
Cello.initializeWithLegacySignature(productId, token, {environment})	Convenience wrapper matching the React Native positional API.
Cello.updateToken(token)	Sends a refreshed token to the SDK. iOS requires 14+.
Cello.changeLanguage(languageCode)	Switches the widget language when supported. iOS requires 14+.
Cello.setThemeMode(themeMode)	Sets the theme mode for the widget (e.g., 'light', 'dark', 'system'). iOS requires 14+.
Cello.showFab() / hideFab()	Controls the out-of-the-box launcher.
Cello.openWidget() / hideWidget()	Manually open/close the referral widget.
Cello.shutdown()	Tears down the SDK (useful when the host user signs out).
Cello.getActiveUcc()	Returns a map describing the user's current UCC (or empty if none).
Cello.getCampaignConfig()	Returns the merged configuration map provided by Cello.
Cello.tokenEvents	Broadcast stream for tokenAboutToExpire / tokenHasExpired.

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.