Flutter SDK

reachbell is the Flutter client SDK — the mobile counterpart to the browser SDK. It acquires the OS push token via firebase_messaging and registers the device with ReachBell, then lets you link the subscription to your own user id and attach tags. Sending pushes and building campaigns happen server-side with the Node server SDK.

Preview: this package is newly released and has not yet been compiled or analyzed against a Dart/Flutter toolchain. Verify register() / identify() / tag() on a real device before shipping — emulators and the iOS Simulator cannot deliver real push tokens reliably.

Install

 Copydependencies:
  reachbell: ^0.1.0

 Copyflutter pub get

Setup

ReachBell delivers Android and iOS push through Firebase Cloud Messaging, so the device token is obtained via firebase_messaging. You must set up a Firebase project first:

1. Create a Firebase project and add your Android and/or iOS app to it (console.firebase.google.com).
2. Add the Firebase config to your app — the easiest path is the FlutterFire CLI:

    Copydart pub global activate flutterfire_cli
   flutterfire configure

   This generates lib/firebase_options.dart and wires the native config files.
3. Add firebase_core and initialize it before using ReachBell:

    Copydependencies:
     firebase_core: ^3.0.0
     reachbell: ^0.1.0

Android

• Place google-services.json in android/app/ (the FlutterFire CLI does this).
• Apply the Google Services Gradle plugin (com.google.gms.google-services).
• On Android 13+ (API 33) the app must hold the POST_NOTIFICATIONS permission. register() requests it at runtime, but you should also declare it in android/app/src/main/AndroidManifest.xml:

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

iOS

• Add GoogleService-Info.plist to the Runner target in Xcode.
• Enable the Push Notifications capability and the Background Modes → Remote notifications capability for the Runner target.
• Upload your APNs authentication key (or certificate) to the Firebase console (Project Settings → Cloud Messaging). Without this, FCM cannot mint a token and register() will throw.
• Push notifications do not work on the iOS Simulator — test on a physical device.

See the firebase_messaging setup guide for the authoritative, version-specific steps.

Initialize

Configure ReachBell once, after Firebase.initializeApp():

 Copyimport 'package:firebase_core/firebase_core.dart';
import 'package:flutter/widgets.dart';
import 'package:reachbell/reachbell.dart';
import 'firebase_options.dart';
 
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
 
  // Configure ReachBell once, after Firebase is ready.
  ReachBell.init(apiKey: 'rb_live_…');
 
  runApp(const MyApp());
}

init({ required String apiKey, String? apiUrl }) sends the key as the x-api-key header. apiUrl defaults to https://api.reachbell.com.

Register for push

register() requests notification permission, reads the device push token via firebase_messaging, then POSTs it to ReachBell. It returns a RegisterResult and caches the token in memory for later identify() / tag() calls.

 Copyfinal result = await ReachBell.register();
print('Registered: ${result.token}');

RegisterResult exposes the registered subscription:

The token from the last successful register() in this process is also available as ReachBell.token (or null if you haven't registered yet).

The token is kept in memory only and is not persisted across app restarts. Because registration is safe to repeat — the server upserts by token, and FCM may rotate tokens anyway — the recommended pattern is to call register() on every launch. You can also listen to FirebaseMessaging.instance.onTokenRefresh and re-run register() when the token rotates.

Identify

Link the registered device to your own user id (for example, after login):

 Copyawait ReachBell.identify('user_42');

You can also link the user in the same call as registration:

 Copyawait ReachBell.register(externalId: 'user_42');

The same externalId is how the Node server SDK targets a user when sending a transactional push. identify() must run after a successful register().

Tag

Attach segmentation tags to the registered subscriber:

 Copyawait ReachBell.tag(['pro', 'beta']);

Errors

Every method throws a ReachBellException when something goes wrong:

• init() not called, or register() not run before identify() / tag().
• Notification permission denied, or no device token could be obtained.
• A non-2xx API response — statusCode and body are populated.
• A network failure or timeout — statusCode is null.

 Copytry {
  final result = await ReachBell.register();
  await ReachBell.identify('user_42');
  await ReachBell.tag(['pro', 'beta']);
} on ReachBellException catch (e) {
  // Permission denied, no token, or a non-2xx API response.
  print('${e.statusCode}: ${e.message}');
}