react-native-apns-kit

A React Native TurboModule that bridges Apple’s APNs (Apple Push Notification Service) APIs for iOS.
This library lets your React Native app or App Clip request push-notification permission, register with APNs, and retrieve the device token needed to send push notifications from your backend.

[!NOTE]

• This library was originally built for my work app, which uses the Bare React Native CLI (non-Expo).
• I’ve open-sourced it so the wider React Native community can easily integrate APNS Support.
• Pull requests are welcome — especially for Expo support (via custom config plugins) or additional native enhancements.

📦 Installation

npm install react-native-apns-kit

Then install pods:

cd ios && pod install

[!IMPORTANT]

• iOS only (works for full apps, App Clips, and extensions).
• The library does not handle local or scheduled notifications — it focuses purely on permission and token registration.

✅ Required native setup (must-do)

Enable Push Notifications capability in Xcode

In Xcode, select your App target (and App Clip target if used) → Signing & Capabilities → + Capability → Push Notifications.

Set aps-environment entitlement

Xcode will add an entitlements file automatically when you add Push Notifications. Confirm your *.entitlements file contains:

<key>aps-environment</key>
<string>development</string>

Use development for debug builds; production for App Store / production provisioning.

App ID / Provisioning profile

In Apple Developer portal, for your App ID (and App Clip App ID), enable Push Notifications.

Recreate/download provisioning profiles so they include the push entitlement and install them in Xcode.

🧰 AppDelegate Setup

In your AppDelegate.swift, add:

  func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let tokenParts = deviceToken.map { String(format: "%02x", $0) }
    let token = tokenParts.joined()

    print("✅ APNs Device Token:", token)
    
    UserDefaults.standard.set(token, forKey: "AppAPNSToken")
    UserDefaults.standard.synchronize()
}

func application(_ application: UIApplication,
                    didFailToRegisterForRemoteNotificationsWithError error: Error) {
      print("❌ Failed to register for APNs:", error.localizedDescription)
    }

These callbacks are required — they’re how iOS delivers the token back to your app.

🔗 Reference Links

• 📘 Apple Docs: Registering for Remote Notifications
• 🔔 Apple Docs: Handling Notifications in Your App
• 🧾 Apple Developer: About Push Notifications

 Why This Library Exists

Most React Native push libraries wrap Firebase or third-party SDKs. If you only need native APNs registration — for enterprise, App Clips, or direct APNs backends — this lightweight module does exactly that and nothing more.

Built for production use in real apps, now open-sourced for the community.

🧠 What It Does

This module wraps Apple’s UNUserNotificationCenter and UIApplication APIs and exposes:

{
  requestNotificationPermission(): Promise<boolean>;
  getAPNSToken(): Promise<string>;
}

Example token (hex):

b0f6c67e7e81f9fa5e6c29163ce3a4b7e61d4c390f021f173b7d69c4e6c9c812

⚙️ Usage

import { requestNotificationPermission, getAPNSToken } from 'react-native-apns-kit';
import { Alert } from 'react-native';

export async function registerForPush() {
  try {
    const granted = await requestNotificationPermission();
    if (!granted) {
      Alert.alert(
        'Notifications Disabled',
        'Enable notifications in Settings.'
      );
      return;
    }

    const token = await getAPNSToken();
    console.log('📲 APNs Token:', token);

    // Send to your backend for push targeting
    await fetch('https://your-backend.com/api/register-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token }),
    });
  } catch (err: any) {
    Alert.alert('Error', err.message);
  }
}

🧩 Supported Platforms

| Platform | Status | | ---------------------------- | ---------------------- | | iOS (13+) | ✅ Fully supported | | App Clip | ✅ Supported | | Android | 🚫 Not applicable | | Web | 🚫 Not applicable | | Expo (Custom Dev Client) | ✅ Works automatically |

🛠️ Under the Hood

This module wraps:

UNUserNotificationCenter.requestAuthorization(options)
UIApplication.registerForRemoteNotifications()
application:didRegisterForRemoteNotificationsWithDeviceToken

and saves the resulting token into NSUserDefaults (or App Group if configured) so the JS layer can safely retrieve it via TurboModule.

🤝 Contributing

Pull requests are welcome — especially improvements for Swift extensions or App Group support!

• Development workflow
• Sending a pull request
• Code of conduct

🪪 License

MIT © Gautham Vijayan

Made with create-react-native-library