Push notifications

The SDK ships a SwanMessagingService that subclasses FirebaseMessagingService and is declared in the SDK's own AndroidManifest.xml. You don't need to add anything to your manifest.

What you do need:

1. Add google-services.json from your Firebase console to app/
2. Apply the Google Services plugin in your app-level build.gradle.kts:

plugins {
    id("com.android.application")
    id("kotlin-android")
    id("com.google.gms.google-services")  // ← this
}

3. Initialize the SDK in Application.onCreate() (covered in Getting started)

That's it. Token registration, refresh, and message delivery all run inside the SDK.

In your AppDelegate:

import SwanSDK
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Swan.shared.initialize(appId: "your-app-id")
        UNUserNotificationCenter.current().delegate = self
        application.registerForRemoteNotifications()
        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        Swan.shared.registerAPNsToken(deviceToken)
    }
}

Implement UNUserNotificationCenterDelegate to forward incoming notification taps into the SDK (see Getting started → iOS for the full delegate snippet).

The SDK delivers pushes through React Native Firebase + Notifee. Register all handlers at module scope in index.js (not inside a component) so background and killed-state deliveries fire before the React tree mounts.

// index.js
import messaging from '@react-native-firebase/messaging';
import notifee from '@notifee/react-native';
import {
    createForegroundMessageHandler,
    createBackgroundMessageHandler,
    createNotificationOpenedHandler,
    createNotifeeForegroundHandler,
    createNotifeeBackgroundHandler,
} from '@loyalytics/swan-react-native-sdk';

messaging().onMessage(createForegroundMessageHandler());
messaging().setBackgroundMessageHandler(createBackgroundMessageHandler());

notifee.onForegroundEvent(createNotifeeForegroundHandler());
notifee.onBackgroundEvent(createNotifeeBackgroundHandler());

// iOS carousel taps surface through this Firebase handler — Notifee click
// handlers do not fire for carousel deliveries displayed natively by iOS.
messaging().onNotificationOpenedApp(createNotificationOpenedHandler());

Then enable push during SDK init:

import SwanSDK from '@loyalytics/swan-react-native-sdk';

const sdk = SwanSDK.getInstance('your-app-id', {
    isProduction: true,
    pushNotifications: { enabled: true },
});

On iOS, image and carousel pushes additionally require a Notification Service Extension (and, for carousel, a Notification Content Extension) — see iOS — Rich pushes and extensions.

Web push uses the Web Push (VAPID) standard. The SDK ships a Service Worker; serve dist/sw.js from @loyalytics/swan-web-sdk at /swan-service-worker.js on your origin (see the getting-started guide for build-tool recipes). The SDK reads your per-tenant VAPID public key from the device-register response automatically — no key copy/paste needed:

import { Swan } from '@loyalytics/swan-web-sdk';

Swan.initialize('your-app-id', { production: true });

if (await Swan.isPushSubscribed()) {
  // Already opted in — nothing to do.
} else {
  // Show your "Enable notifications" CTA. Call subscribeToPush() on click.
  const subscribed = await Swan.subscribeToPush();
  // → true on success; false if permission denied or browser unsupported.
}

Swan.addNotificationOpenedListener(({ route, keyValuePairs }) => {
  if (route) router.push(route);
});

Coverage: Chrome / Edge / Firefox (desktop + Android) — full · Safari macOS 13+ — full · iOS Safari 16.4+ — only when installed as a PWA · iOS Safari < 16.4 — not supported (SDK returns false from subscribeToPush gracefully).

The SDK pre-registers five default channels on first init:

The campaign payload chooses the channel by ID — you don't have to do anything unless you want a custom-sound channel (the OS binds the sound to the channel at creation, so you can't change a sound on an existing channel):

import cx.swan.sdk.Swan
import cx.swan.sdk.SWAN_NOTIFICATION_CHANNELS

Swan.createNotificationChannel(
    channelId = "order_updates",
    channelName = "Order updates",
    importance = SWAN_NOTIFICATION_CHANNELS.IMPORTANCE_HIGH,
    soundResName = "order_chime",  // res/raw/order_chime.mp3
)

Call this once at app launch (it's idempotent — calling it again on the same channelId is a no-op).

iOS doesn't have OS-level channels; UNNotificationCategory serves a similar role. The SDK pre-registers the five default categories at init (their ids are exposed as SwanNotificationChannels.transactional, .alerts, .promotional, .general, .default) — these are the same string values as the Android channel ids, so campaign payloads work cross-platform without a remap.

Custom UNNotificationCategory registration (action buttons, custom intents) is a host-app concern — register your categories via UNUserNotificationCenter.current().setNotificationCategories(_:) directly, and have the campaign payload reference your category id.

The SDK pre-registers five default channels on first init. On Android these are OS-level notification channels; on iOS the equivalent UNNotificationCategory entries are registered under the same string IDs so campaign payloads work cross-platform without a remap.

The campaign payload chooses the channel by ID — you don't have to do anything unless you want a custom-sound channel (the OS binds the sound to the channel at creation, so you can't change a sound on an existing channel).

import SwanSDK, {
    SWAN_NOTIFICATION_CHANNELS,
} from '@loyalytics/swan-react-native-sdk';

const sdk = SwanSDK.getCurrentInstance();

console.log(SWAN_NOTIFICATION_CHANNELS.TRANSACTIONAL); // 'swan_transactional'

// Custom channel (Android only — no-op on iOS):
await sdk?.createNotificationChannel(
    'Order updates',     // channelName
    4,                   // importance (4 = High)
    'Shipping + delivery',
    'order_updates',     // channelId
    'order_chime'        // sound file in res/raw/
);

Web Notifications API has no channel concept; styling is controlled at the campaign level.

On Android 13+ (API 33) notification permission is runtime, like camera or location. Earlier versions auto-grant.

class MyActivity : AppCompatActivity() {
    override fun onResume() {
        super.onResume()
        Swan.setCurrentActivity(this)   // required for the permission dialog
    }

    override fun onPause() {
        Swan.setCurrentActivity(null)
        super.onPause()
    }

    private fun askForPushPermission() {
        lifecycleScope.launch {
            val granted = Swan.requestNotificationPermission()
            if (granted) {
                // happy path
            } else {
                // user denied — show a soft prompt explaining what they'll miss
            }
        }
    }
}

requestNotificationPermission is a suspend function that returns Boolean. The OS dialog needs an Activity context — register the current Activity via Swan.setCurrentActivity(this) in onResume. If you forget, the call still resolves (returning false) but no dialog will appear.

Best practice: don't ask at first launch — ask after the user has done one meaningful action (signed in, added to cart, completed onboarding). Permission denials are sticky on Android.

let granted = await Swan.shared.requestNotificationPermission()

Same principle: ask after a meaningful action, not at cold launch. iOS denials are also sticky and the user has to go to Settings to flip them back.

const sdk = SwanSDK.getCurrentInstance();
const granted = await sdk?.requestNotificationPermission();

Handles the platform differences (Android 13+ runtime prompt, iOS prompt, older Android auto-grant) internally.

const granted = await Swan.requestPushPermission();

Browser permission UI varies — Chrome / Edge show inline prompts; Safari uses its own model. The SDK exposes the boolean outcome consistently.

Swan.addPushNotificationReceivedListener { payload ->
    Log.d("MyApp", "push received: ${payload.messageId}")
}

Payload structure — PushNotificationReceivedPayload:

The event fires only for foreground deliveries, BEFORE the SDK posts the system notification. Background / killed-state pushes route through the tap path (addNotificationOpenedListener) without firing this event. The event is not buffered — late subscribers do not see prior pushes.

Swan.shared.addPushNotificationReceivedListener { payload in
    print("push received:", payload.messageId ?? "(no id)")
}

Payload structure — PushNotificationReceivedPayload:

Fires only for foreground deliveries, BEFORE the SDK posts the system notification. Background / killed-state pushes route through addNotificationOpenedListener. Not buffered — late subscribers do not see prior pushes.

import SwanSDK from '@loyalytics/swan-react-native-sdk';

const sdk = SwanSDK.getCurrentInstance();

sdk?.addEventListener(SwanSDK.EVENTS.PUSH_NOTIFICATION_RECEIVED, (notification) => {
    console.log('push received:', notification);
});

Payload structure — the raw FCM RemoteMessage delivered to the foreground handler. The most common fields:

PUSH_NOTIFICATION_RECEIVED fires only for foreground data-only messages received via messaging().onMessage. Background and killed-state deliveries route through the tap path (NOTIFICATION_OPENED).

Swan.addPushNotificationReceivedListener((payload) => {
    console.log('push received:', payload.messageId);
});

Payload structure — PushNotificationReceivedPayload:

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Required on cold-start to capture the launching intent
        Swan.handleNotificationIntent(intent)

        Swan.addDeepLinkOpenedListener { payload ->
            payload.route?.let { navController.navigate(it) }
        }
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        // Required on warm-start (notification tap while app is backgrounded)
        Swan.handleNotificationIntent(intent)
    }
}

Cold-start gotcha: the SDK deduplicates by messageId for 30 seconds. Calling handleNotificationIntent from both onCreate and onNewIntent is safe — only one delivery fires for any given message.

Payload structure — NotificationOpenedPayload (delivered to addNotificationOpenedListener):

DeepLinkOpenedPayload (delivered to addDeepLinkOpenedListener) has route, keyValuePairs, and extras with the same semantics, plus a source: DeepLinkOpenedPayload.Source enum (PUSH, EMAIL, SMS, DEEP_LINK) indicating where the deep link originated.

Swan.shared.addDeepLinkOpenedListener { payload in
    if let route = payload.route { router.navigate(to: route) }
}

// Forward UNUserNotificationCenter callbacks into
// Swan.shared.handleNotificationUserInfo(_:) from your
// UNUserNotificationCenterDelegate to drive cold-start + warm-start.

Payload structure — NotificationOpenedPayload (delivered to addNotificationOpenedListener):

DeepLinkOpenedPayload (delivered to addDeepLinkOpenedListener) has route, keyValuePairs, and extras with the same semantics, plus a source: DeepLinkOpenedPayload.Source enum (.push, .email, .sms, .deepLink) indicating where the deep link originated.

import SwanSDK from '@loyalytics/swan-react-native-sdk';

useEffect(() => {
    const sdk = SwanSDK.getCurrentInstance();
    const handler = (payload) => {
        if (payload.route) navigation.navigate(payload.route, payload.keyValuePairs);
    };
    const sub = sdk?.addListener(SwanSDK.EVENTS.NOTIFICATION_OPENED, handler);
    return () => sub?.remove();
}, []);

NOTIFICATION_OPENED and DEEP_LINK_OPENED are emitted on the SDK instance and consumed via addListener(event, callback) (returns { remove(): void }). The separate addEventListener API is reserved for FCM-provider events such as PUSH_NOTIFICATION_RECEIVED and TOKEN_RECEIVED.

Payload structure — NotificationOpenedPayload:

DeepLinkOpenedPayload has route, keyValuePairs, and the index signature with the same semantics, plus a source: 'push' | 'email' | 'sms' | 'deepLink' indicating where the deep link originated.

Cold-start is handled automatically via the message handlers registered in index.js — see Getting started → React Native.

Swan.addDeepLinkOpenedListener((payload) => {
    if (payload.route) router.push(payload.route);
});

Web "deep links" route through the SDK's service worker on notification click — the bundled Service Worker forwards the click into the page, and your listener fires on the next message tick.

Payload structure — PushNotificationReceivedPayload (delivered to both addNotificationOpenedListener and addDeepLinkOpenedListener):

val unsubRegistered = Swan.addPushTokenRegisteredListener { event ->
    Log.d("push", "FCM token registered with Swan: ${event.token}")
}

val unsubRefresh = Swan.addPushTokenRefreshListener { event ->
    Log.d("push", "FCM token rotated: ${event.token}")
}

val unsubFailed = Swan.addPushTokenRegistrationFailedListener { event ->
    Log.w("push", "token subscribe failed: ${event.error.message}")
}

Payload structure — TelemetryEvent.PushTokenRegistered and TelemetryEvent.PushTokenRefreshed:

addPushTokenRegisteredListener fires on every successful subscribe with the Swan backend (initial registration AND every rotation). It buffers the most recent token, so late subscribers receive the current token synchronously on subscribe.

addPushTokenRefreshListener fires only on FCM token rotation (onNewToken) — not on the initial registration. Useful if you maintain your own copy of the token in a remote backend.

Payload structure — TelemetryEvent.PushTokenRegistrationFailed:

The SDK continues to function — events keep queuing locally and the next onNewToken or Swan.registerFcmToken(...) call retries the subscribe.

let unsubRegistered = Swan.shared.addPushTokenRegisteredListener { payload in
    print("APNs token registered with Swan:", payload.token)
}

let unsubRefresh = Swan.shared.addPushTokenRefreshListener { payload in
    print("APNs token rotated:", payload.token)
}

let unsubFailed = Swan.shared.addPushTokenRegistrationFailedListener { payload in
    print("token subscribe failed:", payload.error.localizedDescription)
}

let unsubPermission = Swan.shared.addPushPermissionListener { event in
    // event is `.permissionGranted` or `.permissionDenied`
}

Payload structure — PushTokenRegisteredPayload and PushTokenRefreshPayload:

addPushTokenRegisteredListener fires on every successful APNs-token registration with the Swan backend (including the initial registration). Re-registering the same token bytes the SDK already holds short-circuits without re-emitting.

addPushTokenRefreshListener fires only when a re-registration replaces a previous token. The initial registration does NOT fire this surface.

Payload structure — PushTokenRegistrationFailedPayload:

The SDK continues to function — events queue locally and the next Swan.shared.registerAPNsToken(_:) call retries the subscribe.

addPushPermissionListener callback receives a PushLifecycleEvent — .permissionGranted or .permissionDenied — fired on every requestNotificationPermission() resolution.

import SwanSDK from '@loyalytics/swan-react-native-sdk';

const sdk = SwanSDK.getCurrentInstance();

sdk?.addEventListener(SwanSDK.EVENTS.TOKEN_RECEIVED, (token) => {
    console.log('FCM token received:', token);
});

sdk?.addEventListener(SwanSDK.EVENTS.TOKEN_REFRESH, (newToken) => {
    console.log('FCM token rotated:', newToken);
});

sdk?.addEventListener(SwanSDK.EVENTS.PERMISSION_CHANGED, (granted) => {
    console.log('permission:', granted ? 'granted' : 'denied');
});

Callback payloads:

Listeners registered before push initialization are queued and attached when push init completes.

The Web SDK does not expose a separate token-received listener — the Push API subscription is managed through subscribeToPush() / isPushSubscribed() / unsubscribePush(). Permission state changes are observable via the browser's Permissions API:

const status = await navigator.permissions.query({ name: 'notifications' });
status.onchange = () => {
    console.log('permission now:', status.state);
};