@aspect-music/localnotification-react-native

React Native SDK for LocalNotification - Remote local notification management with user segmentation and analytics.

Features

• Remote configuration of local notifications
• User segmentation with custom properties
• Automatic session tracking for analytics
• Support for immediate, scheduled, and recurring notifications
• Text interpolation with user properties
• Expo Notifications integration

Installation

npm install @aspect-music/localnotification-react-native
# or
yarn add @aspect-music/localnotification-react-native
# or
pnpm add @aspect-music/localnotification-react-native

Peer Dependencies

npm install expo-notifications react react-native

Quick Start

1. Provider Setup

Wrap your app with LocalNotificationProvider:

import { LocalNotificationProvider } from '@aspect-music/localnotification-react-native';

export default function App() {
  return (
    <LocalNotificationProvider
      config={{
        apiUrl: 'https://your-api.com',
        appId: 'your-app-id',
        apiKey: 'your-api-key', // optional
        syncInterval: 60000, // sync every 60 seconds
        trackSessions: true, // enable session tracking for analytics
      }}
    >
      <YourApp />
    </LocalNotificationProvider>
  );
}

2. Using the Context Hook

import { useLocalNotificationContext } from '@aspect-music/localnotification-react-native';

function MyComponent() {
  const {
    notifications,
    segments,
    isInitialized,
    isLoading,
    error,
    sync,
    setUserContext,
    updateUserProperties,
    triggerNotification,
  } = useLocalNotificationContext();

  // Set user context with properties for segmentation
  useEffect(() => {
    setUserContext({
      userId: 'user-123',
      locale: 'en',
      timezone: 'America/New_York',
      properties: {
        total_played_games: 25,
        is_premium: true,
        level: 10,
      },
    });
  }, []);

  // Update user properties dynamically
  const handleGameComplete = async () => {
    await updateUserProperties({
      total_played_games: 26,
      last_game_date: new Date().toISOString(),
    });
  };

  return (
    <View>
      <Text>Notifications: {notifications.length}</Text>
      <Button title="Refresh" onPress={sync} disabled={isLoading} />
    </View>
  );
}

3. Standalone Hook Usage

For simpler use cases without context:

import { useLocalNotifications } from '@aspect-music/localnotification-react-native';

function MyComponent() {
  const {
    notifications,
    segments,
    isInitialized,
    isLoading,
    error,
    sync,
    setUserContext,
    updateUserProperties,
    triggerNotification,
  } = useLocalNotifications({
    apiUrl: 'https://your-api.com',
    appId: 'your-app-id',
  });

  // ...
}

4. Direct SDK Usage

For advanced use cases:

import { createLocalNotificationSDK } from '@aspect-music/localnotification-react-native';

const sdk = createLocalNotificationSDK({
  apiUrl: 'https://your-api.com',
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  trackSessions: true,
});

await sdk.initialize();

// Set user context
await sdk.setUserContext({
  userId: 'user-123',
  properties: {
    total_played_games: 25,
    is_premium: true,
  },
});

// Update properties
await sdk.updateUserProperties({
  total_played_games: 26,
});

// Manual sync
await sdk.sync();

// Trigger a notification immediately
await sdk.triggerImmediate('notification-id');

// Get cached data
const notifications = sdk.getNotifications();
const segments = sdk.getSegments();
const userContext = sdk.getUserContext();

// Cleanup
await sdk.destroy();

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiUrl | string | required | Base URL of your LocalNotification API | | appId | string | required | Your application ID | | apiKey | string | optional | API key for authentication | | syncInterval | number | 60000 | Auto-sync interval in milliseconds | | trackSessions | boolean | true | Enable automatic session tracking |

User Segmentation

The SDK automatically filters notifications based on user segments defined in the admin panel.

Setting User Properties

// Via context
await setUserContext({
  userId: 'user-123',
  properties: {
    total_played_games: 25,
    is_premium: true,
    country: 'US',
  },
});

// Update specific properties
await updateUserProperties({
  total_played_games: 26,
  last_login: new Date().toISOString(),
});

Segment Rules

Segments are defined in the admin panel with rules like:

• total_played_games > 20
• is_premium = true
• country in ["US", "CA", "UK"]

Notifications attached to a segment will only be shown to matching users.

Text Interpolation

Notification titles and bodies support dynamic text using {{property}} syntax:

Title: "Welcome back, {{userId}}!"
Body: "You've played {{total_played_games}} games!"

Session Tracking

When trackSessions is enabled, the SDK automatically tracks:

• Session start when app becomes active
• Session end when app goes to background

This data powers the analytics dashboard with:

• DAU/WAU/MAU metrics
• Retention cohorts
• Segment comparison

Notification Types

Immediate

Displayed immediately when conditions are met.

Scheduled

Displayed at a specific date and time.

Recurring

Displayed on a schedule:

• Daily at a specific time
• Weekly on specific days
• Monthly on a specific day

TypeScript Support

Full TypeScript support with exported types:

import type {
  SDKConfig,
  UserContext,
  Notification,
  UserProperties,
  Condition,
  Trigger,
  Segment,
} from '@aspect-music/localnotification-react-native';

API Reference

LocalNotificationProvider

| Prop | Type | Description | |------|------|-------------| | config | SDKConfig | SDK configuration | | children | ReactNode | Child components | | autoInitialize | boolean | Auto-initialize on mount (default: true) |

useLocalNotificationContext / useLocalNotifications

Returns:

• notifications: Notification[] - Cached notifications
• segments: SegmentInfo[] - Available segments
• isInitialized: boolean - SDK initialization status
• isLoading: boolean - Loading state
• error: Error | null - Last error
• sync(): Promise<void> - Manual sync
• setUserContext(context): Promise<void> - Set user context
• updateUserProperties(props): Promise<void> - Update user properties
• triggerNotification(id): Promise<void> - Trigger notification

LocalNotificationSDK

Methods:

• initialize(): Promise<void>
• setUserContext(context: UserContext): Promise<void>
• updateUserProperties(properties: UserProperties): Promise<void>
• sync(): Promise<SyncResponse>
• syncDelta(): Promise<SyncResponse>
• triggerImmediate(notificationId: string): Promise<void>
• getNotifications(): Notification[]
• getSegments(): SegmentInfo[]
• getUserContext(): UserContext
• stopAutoSync(): void
• destroy(): Promise<void>

License

MIT