Skip to main content

​
Push Notifications

Push notifications use OneSignal for delivery. The SDK handles initialization, permission requests, device registration, and notification interaction tracking automatically.

​
Setup

  1. Create a OneSignal app and get your OneSignal App ID
  2. Configure it in your Stackfront dashboard
  3. The SDK fetches the OneSignal App ID from remote config and initializes automatically

​
How It Works

When StackfrontProvider initializes:
  1. OneSignal is initialized with the app ID from remote config
  2. Permission is requested automatically via the usePush hook
  3. Device is registered with the Stackfront API (platform, app version, device model, OS version)
  4. Notification clicks are tracked — when a user taps a notification containing a campaign_id, an open event is sent to the API

​
Hook API

function usePush(): {
  permission: boolean;
  requestPermission: () => Promise<boolean>;
  preferences: NotificationPreference | null;
  loading: boolean;
  error: Error | null;
  updatePreferences: (prefs: {
    marketingEnabled: boolean;
    transactionalEnabled: boolean;
    abandonedCartEnabled: boolean;
    orderUpdatesEnabled: boolean;
    promotionsEnabled: boolean;
  }) => Promise<void>;
  refetchPreferences: () => Promise<void>;
}

​
Permission Handling

import { usePush } from 'react-native-stackfront-sdk';

function NotificationSettings() {
  const { permission, requestPermission, preferences, updatePreferences } = usePush();

  return (
    <View>
      <Text>
        Notifications: {permission ? 'Enabled' : 'Disabled'}
      </Text>
      {!permission && (
        <Button title="Enable Notifications" onPress={requestPermission} />
      )}

      {preferences && (
        <>
          <SwitchRow
            label="Marketing"
            value={preferences.marketingEnabled}
            onValueChange={(v) => updatePreferences({ ...preferences, marketingEnabled: v })}
          />
          <SwitchRow
            label="Order Updates"
            value={preferences.orderUpdatesEnabled}
            onValueChange={(v) => updatePreferences({ ...preferences, orderUpdatesEnabled: v })}
          />
          <SwitchRow
            label="Abandoned Cart"
            value={preferences.abandonedCartEnabled}
            onValueChange={(v) => updatePreferences({ ...preferences, abandonedCartEnabled: v })}
          />
        </>
      )}
    </View>
  );
}

​
Customer Linking

When a customer logs in, the SDK automatically links their OneSignal player ID to their customer ID. This enables targeted notifications: 
// This happens automatically in useCustomer().login():
devices.linkCustomer(customerId);

​
Notification Click Tracking

When a user taps a push notification with a campaign_id in its additionalData, a click event is sent to the Stackfront API: 
POST /api/v1/sdk/notifications/track-open
{ campaign_id: "abc", player_id: "xxx" }

​
Service API

const { devices } = useStackfront();

await devices.requestPermission();         // request iOS/Android permission
await devices.unsubscribe();               // opt out completely
await devices.getPreferences(customerId);  // fetch notification preferences
await devices.updatePreferences(customerId, prefs); // update preferences
devices.getPlayerId();                     // get current OneSignal player ID

​
OneSignal Integration

If you need to use OneSignal APIs directly outside the SDK, import OneSignal: 
import { OneSignal } from 'react-native-onesignal';
OneSignal.User.pushSubscription.getIdAsync(); // get player ID