react-native-notiflink

A unified library for handling push notifications and deep links in React Native applications. Designed to solve the common challenge of managing notifications and deep links across all app states, including when the app is completely terminated.

Overview

react-native-notiflink provides a single, consistent API for:

• Push notifications (local and remote)
• Deep link handling (custom URL schemes and universal links)
• Permission management across iOS and Android
• Reliable navigation from killed app state

This library eliminates the need to manage multiple packages and write complex state-handling logic.

Installation

npm install react-native-notiflink

or

yarn add react-native-notiflink

iOS Setup

1. Install pods:

cd ios && pod install

2. Add the following to your Info.plist for deep link support:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

3. Enable push notifications capability in Xcode:
   • Open your project in Xcode
   • Select your target
   • Go to "Signing & Capabilities"
   • Click "+ Capability" and add "Push Notifications"

Android Setup

1. Add the following to your AndroidManifest.xml for deep link support:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="yourapp" />
</intent-filter>

2. For Android 13+ notification permissions, the library handles runtime permission requests automatically.

Quick Start

import NotifLink from 'react-native-notiflink';

// Configure the library on app startup
NotifLink.configure({
  onDeepLink: (link) => {
    console.log('Deep link opened:', link.url);
    // Navigate to the appropriate screen
  },
  onNotificationOpened: (notification) => {
    console.log('Notification opened:', notification);
    // Handle notification tap
  },
  notifications: {
    requestPermissionsOnInit: true,
  },
});

API Reference

configure(config: NotifLinkConfig): Promise<void>

Initializes the library with the provided configuration. This should be called once during app startup.

Parameters:

• config.onDeepLink (optional): Callback invoked when a deep link is opened
• config.onNotificationOpened (optional): Callback invoked when a notification is tapped
• config.notifications.requestPermissionsOnInit (optional): Whether to request notification permissions immediately (default: false)

Example:

await NotifLink.configure({
  onDeepLink: (link) => {
    if (link.url.includes('/profile/')) {
      const userId = link.url.split('/profile/')[1];
      navigation.navigate('Profile', { userId });
    }
  },
  onNotificationOpened: (notification) => {
    if (notification.data?.screen) {
      navigation.navigate(notification.data.screen);
    }
  },
});

requestPermissions(): Promise<boolean>

Requests notification permissions from the user.

Returns: A promise that resolves to true if permissions are granted, false otherwise.

Example:

const granted = await NotifLink.requestPermissions();
if (granted) {
  console.log('Notification permissions granted');
}

showLocalNotification(notification: NotificationData): Promise<void>

Displays a local notification.

Parameters:

• notification.title (optional): Notification title
• notification.body (optional): Notification body text
• notification.data (optional): Custom data payload
• notification.deepLink (optional): Deep link to open when notification is tapped

Example:

await NotifLink.showLocalNotification({
  title: 'Order Shipped',
  body: 'Your order #12345 has been shipped',
  deepLink: 'myapp://orders/12345',
  data: {
    orderId: '12345',
    type: 'shipping_update',
  },
});

onDeepLink(handler: (link: DeepLinkData) => void): () => void

Registers a handler for deep link events. Returns an unsubscribe function.

Example:

const unsubscribe = NotifLink.onDeepLink((link) => {
  console.log('Deep link:', link.url);
  console.log('From notification:', link.fromNotification);
});

// Later, to unsubscribe:
unsubscribe();

Usage Examples

Handling Deep Links from Killed State

The library automatically queues deep links received when the app is not running and delivers them once the JavaScript context is ready.

import { useEffect } from 'react';
import NotifLink from 'react-native-notiflink';
import { useNavigation } from '@react-navigation/native';

function App() {
  const navigation = useNavigation();

  useEffect(() => {
    NotifLink.configure({
      onDeepLink: (link) => {
        // This will be called even if the app was killed
        const route = parseDeepLink(link.url);
        navigation.navigate(route.screen, route.params);
      },
    });
  }, []);

  return <YourAppContent />;
}

Requesting Permissions Before Showing Notifications

async function sendNotification() {
  const hasPermission = await NotifLink.requestPermissions();

  if (!hasPermission) {
    Alert.alert('Permission Denied', 'Cannot send notifications');
    return;
  }

  await NotifLink.showLocalNotification({
    title: 'Hello',
    body: 'This is a test notification',
  });
}

Handling Notification Data

NotifLink.configure({
  onNotificationOpened: (notification) => {
    const { data } = notification;

    switch (data?.type) {
      case 'message':
        navigation.navigate('Chat', { chatId: data.chatId });
        break;
      case 'order':
        navigation.navigate('OrderDetails', { orderId: data.orderId });
        break;
      default:
        navigation.navigate('Home');
    }
  },
});

TypeScript Support

The library is written in TypeScript and provides full type definitions.

import NotifLink, {
  NotifLinkConfig,
  NotificationData,
  DeepLinkData,
} from 'react-native-notiflink';

Troubleshooting

Deep links not working on iOS

Ensure you have added the URL scheme to your Info.plist and that the scheme matches what you're using in your deep links.

Notifications not showing on Android

For Android 13 and above, ensure you have requested the POST_NOTIFICATIONS permission. The library handles this automatically when you call requestPermissions().

App crashes when tapping notification

Verify that your navigation setup is complete before calling NotifLink.configure(). The library may attempt to deliver queued notifications immediately after configuration.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Made with create-react-native-library