React Native Package Documentation

Mobile notification support for React Native applications with push notification handling and unified service integration. This package provides comprehensive mobile notification capabilities for iOS and Android.

Installation

npm install @sparkstrand/notifications-react-native

This package requires @sparkstrand/notifications-core as a peer dependency and integrates with the unified notification service.

Setting Up Your App

App Registration

Before using notifications, your app must register with the notification service using your own provider API keys. This ensures complete isolation from other applications.

// In your app initialization
import {notificationService} from '@sparkstrand/notifications-core';

await notificationService.registerApp({
  appId: 'sporty-expats',
  name: 'SportyExpats',
  providers: {
    novu: {
      apiKey: process.env.SPORTY_EXPATS_NOVU_API_KEY,
      appId: process.env.SPORTY_EXPATS_NOVU_APP_ID,
      priority: 1
    },
    resend: {
      apiKey: process.env.SPORTY_EXPATS_RESEND_API_KEY,
      fromEmail: 'notifications@sportyexpats.com',
      priority: 2
    }
  }
});

Provider Configuration

Each app manages its own provider credentials:

  • • Novu: For push notifications, in-app notifications, and multi-channel delivery
  • • Resend: For direct email delivery with custom templates
  • • Twilio: For SMS notifications (when implemented)
  • • Custom providers: Add your own notification providers

Key Features

  • • Push Notifications: Full support for iOS (APNs) and Android (FCM)
  • • In-App Notifications: Rich in-app notification components
  • • Permission Handling: Automatic permission requests and management
  • • Background Processing: Handle notifications when app is in background
  • • Deep Linking: Navigate to specific screens from notifications
  • • Notification Actions: Custom actions and quick replies
  • • Badge Management: Automatic app badge updates
  • • Cross-Platform: Single API for both iOS and Android
  • • Unified Service Integration: Seamless integration with the notification service

Setup & Configuration

iOS Setup (APNs)

# Add to Info.plist
<key>UIBackgroundModes</key>
<array>
  <string>remote-notification</string>
</array>

# Add capabilities in Xcode
# - Push Notifications
# - Background Modes

Android Setup (FCM)

# Add to android/app/google-services.json
# Download from Firebase Console

# Add to android/build.gradle
classpath 'com.google.gms:google-services:4.3.15'

Usage Examples

Basic Setup with Unified Service

import {notificationService} from '@sparkstrand/notifications-core';
import {useNotifications, usePushNotifications} from
  '@sparkstrand/notifications-react-native';

export default function App() {
  // App registration happens in initialization
  // Use hooks for notification management
  const {notifications, markAsRead} = useNotifications();
  const {requestPermission, token} = usePushNotifications();

  return <YourApp />;
}

Sending Notifications

// Send notification via unified service
const sendWelcomeNotification = async () => {
  try {
    await notificationService.sendNotification(
      'user-123',
      'WELCOME',
      'Welcome to SportyExpats!',
      'We're excited to have you on board.',
      { email: 'user@example.com', firstName: 'John' },
      { appId: 'sporty-expats', channels: { email: true, inApp: true } }
    );
  } catch (error) {
    console.error('Failed to send notification:', error);
  }
};

Push Notification Setup

// Request push notification permissions
const setupPushNotifications = async () => {
  const {status} = await requestPermission();

  if (status === 'granted') {
    // Register device with backend
    await notificationService.registerDevice(
      'sporty-expats',
      'user-123',
      token
    );
  }
};

Available Components

Core Components

  • • NotificationCenter: Main notification display component
  • • NotificationBadge: Unread notification counter
  • • NotificationItem: Individual notification display
  • • NotificationList: Scrollable list of notifications
  • • NotificationPreferences: User preference management

Hooks

  • • useNotifications: Manage in-app notifications
  • • useNotificationPreferences: Handle user preferences
  • • usePushNotifications: Push notification management
  • • useNotificationService: Direct service access

Best Practices

  • • Register early: Register your app during app initialization
  • • Permission handling: Request push permissions at appropriate times
  • • Error handling: Always wrap notification calls in try-catch blocks
  • • Background processing: Handle notifications when app is in background
  • • Deep linking: Implement proper navigation from notifications
  • • Testing: Test on both iOS and Android devices
  • • Provider fallback: Ensure your app works even if primary provider fails