> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackfront.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Push Notifications

# 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

```ts theme={null}
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

```tsx theme={null}
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:

```ts theme={null}
// 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:

```text theme={null}
POST /api/v1/sdk/notifications/track-open
{ campaign_id: "abc", player_id: "xxx" }
```

## Service API

```ts theme={null}
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`:

```ts theme={null}
import { OneSignal } from 'react-native-onesignal';
OneSignal.User.pushSubscription.getIdAsync(); // get player ID
```