Push Notifications

Push is an optional module in simplr_ai 1.2.0. You can enable push, RUM, or both from one SimplrConfig. Simplr stores provider credentials encrypted and sends each notification through your Firebase or Apple account; provider secrets are never included in the mobile app.

Fast path

Application identity is managed once under Dashboard → Workspace → Applications. Create the application there, choose Flutter as its type, assign its environments, and keep the generated application ID for the SDK.

Then open Dashboard → Products → Mobile push. The setup tracker keeps the first successful send to four steps:

1. Select the existing Flutter application and add a test push configuration with its Android package name, iOS bundle ID, or both.
2. Connect Firebase or Apple using the guided provider form.
3. Copy the generated Flutter setup, run the app, and wait for one reachable device.
4. Select Send test next to that device. Move to broader audiences only after the provider accepts the test.

Mobile push never creates a second application. The SDK application key comes from Applications and is shared by RUM and push. The push configuration UUID shown by the API is used only by trusted backend calls.

Connect the provider account

The portal accepts the files supplied by each provider instead of requiring hand-written credential JSON:

• Android / Firebase: upload the service-account JSON downloaded from Firebase console → Project settings → Service accounts → Generate new private key.
• iOS / APNs: upload the .p8 key downloaded from Apple Developer → Certificates, Identifiers & Profiles → Keys, then enter its Key ID and Team ID. The bundle ID comes from the mobile app setup. Test apps use APNs sandbox; live apps use APNs production.

Simplr extracts only the required fields, encrypts the credential on the API, and never returns it. The status remains Stored · test required until a real notification is accepted by the provider. Replacing a credential overwrites the encrypted value for that app and provider.

Configure the mobile app

Complete the standard Firebase Flutter setup for your Android and iOS app. Firebase Messaging obtains the Android FCM token. On iOS, the SDK registers the native APNs token and Simplr sends directly through your APNs key.

import 'package:simplr_ai/simplr_ai.dart';

final simplr = Simplr(SimplrConfig(
  apiKey: 'pk_live_xxx',
  applicationId: 'my-mobile-app', // Push application key
  rum: const SimplrRumConfig(),   // Remove to enable push only
  push: SimplrPushConfig(
    onForegroundMessage: (message) {
      // Render your in-app notification UI.
    },
    onNotificationOpened: (message) {
      // Route using message.data.
    },
  ),
));

await simplr.initialize();

MaterialApp(
  navigatorObservers: simplr.navigatorObservers,
  // ...
);

Call the permission prompt from user-initiated UI, or set requestPermissionOnStart: true:

await simplr.push?.requestPermission();

After initialization, the Mobile push page shows the device under Audience. A denied notification permission is recorded but is not counted as a reachable device.

Identify a user safely

Do not accept a raw user ID from the app as trusted push identity. Your backend requests a five-minute identity assertion using its Simplr secret key:

POST /v1/push-sdk/identity-token
X-API-Key: sk_live_xxx
Content-Type: application/json

{
  "application_id": "the-application-uuid",
  "external_user_id": "customer_123"
}

Return only the assertion to the signed-in app:

await simplr.identify(
  'customer_123',
  pushIdentityAssertion: assertionFromYourBackend,
);

Call await simplr.logout() when the application session ends. This explicitly removes the user association while keeping an anonymous device subscription current. Normal token refreshes preserve the existing verified identity; the short-lived assertion is not reused.

Send

Owners and admins can compose notifications under Products → Mobile push. Start with Send test on one Audience row. After that succeeds, New message can target all subscribed devices, verified external user IDs, or exact subscription IDs, immediately or at a scheduled time.

A trusted backend can also call POST /v1/push-sdk/messages with a secret key. Every request requires an idempotency key.

Provider acceptance and app-confirmed received/clicked counts are reported separately. Mobile operating systems do not guarantee a background delivery callback, so received counts are best-effort and must not be treated as proof that a user saw a notification.

If a provider rejects a credential, Mobile push shows Needs attention with a safe provider error. Replace the credential and send another device test.

Configure and send with Simplr MCP

@simplr-ai/mcp includes the same setup guidance and guarded operational tools. In operations mode:

1. Call list_applications and select an active application whose type is flutter.
2. Call configure_mobile_push for test or live after the operator confirms the exact application and environment.
3. Upload Firebase or Apple credentials in Products → Mobile push. The MCP deliberately cannot accept provider keys, so secrets never enter a chat or tool log.
4. Call list_push_subscriptions, choose a known Test device, and call send_push_notification with an explicit idempotency key and operator_confirmed: true.

For code setup, call get_integration_guide with feature mobile-push and language flutter. A Live audience send always needs a fresh, exact operator confirmation.

Platform scope

The first release supports Android and iOS. Web, rich media, journeys, and automated segmentation are not part of this release.