Ana içeriğe geç

React Native SDK

@opennotification/react-native iOS ve Android'i tek JavaScript API'sinden kapsar ve native tarafın tamamı paketin içinde gelir: @react-native-firebase/* yok, Notifee yok, AsyncStorage yok. iOS native bir modülle doğrudan APNs'e konuşur — Firebase iOS SDK'sı yok. Android, Kotlin SDK'yı Firebase Messaging üzerinde gömülü çalıştırır ve her bildirimi kendisi çizer; Firebase Messaging npm'den değil Gradle'dan gelir.

1 Kur​

bun add @opennotification/react-native

Sonra birini seçin: Expo plugin ya da elle kurulum.

2 Başlat​

import { OpenNotification } from "@opennotification/react-native";

OpenNotification.init({
endpoint: "https://push.example.com",
appKey: "pk_live_…",
autoRegister: false, // true: init sırasında izin iste
androidSmallIcon: "ic_notification", // drawable adı, tek renkli
});

init için await gerekmez: promise döner ama o yüklenirken yapılan her çağrı arkasında kuyruğa girer, dolayısıyla uygulamanızın en üstünde tek başına bir satır olabilir. Yalnızca client nesnesini ya da autoRegister sonucunu isteyeceksen bekle.

init native dinleyicileri bağlar ve Android'de FCM token'ını alıp hemen kaydeder (token almak için izin gerekmez). iOS'ta izin verilene kadar hiçbir şey gönderilmez. index.js'e kaydedilecek bir arka plan handler'ı yok: çizim ve takip native olduğu için FCM'in süreci içinde JavaScript olmadan uyandırması sorun değil.

3 İzin, kimlik, tag'ler, açılmalar​

İzni kullanıcının nedenini anladığı yerde isteyin — ilk açılışta değil, buna ihtiyaç duyan bir özelliği açtıktan sonra:

const result = await OpenNotification.requestPermission();
if (!result.ok) console.warn(result.error.code); // permission_denied | no_token | api_error | network_error

Dinleyiciler bir kez, navigasyonunuzun hazır olduğu yerde bağlanır:

const off = OpenNotification.onOpen((message) => {
navigate(message.data.screen ?? "Home", message.data); // message.url, message.actionId de var
});
OpenNotification.onReceive((message) => {
if (message.silent) sync(message.data); // arka plan push'u: bir şey gösterilmedi, mesaj data'dır
});

Geri kalanı tek bir bloğa değil, uygulamanızdaki anlara aittir:

OpenNotification.login("user_123"); // kendi girişiniz başarılı oldu
OpenNotification.setTags({ plan: "platinum", streak: 42 });
OpenNotification.setEmail("[email protected]"); // null siler
OpenNotification.setPhone("+905551234567"); // E.164, null siler

OpenNotification.logout(); // kendi çıkışınız
OpenNotification.unsubscribe(); // ayarlarınızda bildirimleri kapattı

Hiçbiri throw etmez, yani try edilecek bir şey yok. Promise<Result<…>> dönerler ve await yazmaya ancak sonucu okuyacaksanız değer:

const saved = await OpenNotification.setTags({ plan: "platinum" });
if (!saved.ok) retryLater(); // { code: "network_error" | "api_error" | "not_subscribed", … }

Aksi halde çağırıp bırakmak yeterli — istek çağırdığınız anda kuyruğa girer ve düşen bir tag yazımı için ekranı bekletmeye değmez.

onOpen soğuk açılışta da tetiklenir: uygulamayı başlatan basış bir dinleyici oluşana kadar tutulur, yani init yerleşmeden önce de sonra da kaydolsanız size ulaşır. Yalnızca ilk dinleyici, bir kez alır.

Oturumlar sizin için sayılır: start() AppState'i dinler ve her ön plana dönüşte /session'a ping atar; sunucu 30 dakika boşluk kuralını uygular, çift sayım olmaz. Sessiz push'lar onReceive'e message.silent === true ile gelir — iOS'ta application(_:didReceiveRemoteNotification:fetchCompletionHandler:)'ı OpenNotification.didReceiveBackground(userInfo:)'ya iletin (aşağıdaki AppDelegate) ve Remote notifications background mode'unu açın.

await OpenNotification.permissionStatus() granted | denied | provisional | not_determined döner; OpenNotification.register() kaydı açıkça yeniden gönderir.

removeTags(keys) ve setLanguage(code) da facade üzerinde.

Ön plan, bildirim merkezi, rozet, dönüşümler​

// Açık sohbetin push'larını ekrandayken gizle (onReceive yine tetiklenir).
OpenNotification.setForegroundPresentation({ hideWhen: [{ type: "chat", senderId: "42" }] });
OpenNotification.setForegroundPresentation({}); // yeniden hepsini göster
OpenNotification.setForegroundPresentation({ show: false }); // uygulama açıkken hiçbirini gösterme

OpenNotification.removeNotification("chat_42"); // collapseId "chat_42" ile gelen push
OpenNotification.removeGroup("chat_42"); // presentation.threadId "chat_42" ile gelenlerin hepsi
OpenNotification.clearAll();

OpenNotification.setBadgeCount(3); // iOS; Android launcher'ları sayıyı kendisi çıkarır
OpenNotification.clearBadge();

OpenNotification.onPermissionChange((status) => {}); // ör. Ayarlar'dan kapatıldı
OpenNotification.onSubscriptionChange(({ previous, current }) => {});

await OpenNotification.sendOutcome("purchase", 9.99);
  • Ön plan kuralları push geldiğinde native tarafta karar verilir — iOS delegate'e kısa bir süre tanır, JavaScript'e gidip gelmeye yetmez. Bir kural, andığı her anahtar push'un data değerine eşitse eşleşir. iOS'ta AppDelegate'in OpenNotification.presentationOptions(for:)'u çağırması gerekir (aşağıda).
  • collapseId iki platformda da ekrandaki bildirimin yerine geçer (Android'de SDK aynı collapse id'li her push'u tek bildirim kimliğiyle gösterir). Android'de presentation.threadId taşıyan push'lar ikinciden itibaren bir özetin altında toplanır.
  • Rozet: clearBadgeOnOpen (varsayılan true) OneSignal gibi her ön plana gelişte iOS rozetini sıfırlar. presentation.badgeIncrement mevcut rozete ekler; sayacı servis extension'ı bir App Group'ta tutar, bu yüzden aynı OpenNotificationAppGroup değerini uygulamanın ve extension'ın Info.plist'ine ekleyin.
  • İzin değişiklikleri her ön plana gelişte fark edilir; açıktan kapalıya (ya da tersine) geçiş sunucudaki optedIn alanını da günceller.
  • Dönüşümler: kullanıcı outcomeWindowMinutes (varsayılan 1440) içinde bir bildirimi açtıysa dönüşüm o kampanyaya yazılır ve raporunda görünür; aksi halde atıfsız saklanır. İsimler ^[a-z0-9_-]{1,64}$.

Cihaz bilgileri​

Kayıt ve her oturum pingi OneSignal'ın topladıklarını da taşır; içe aktarılan kitleyle SDK'dan gelen kitle segment ve raporlarda aynı görünür: donanım modeli (iPhone16,1, samsung SM-A566E), OS ve uygulama sürümü, dil, saat dilimi, ülke, root / jailbreak (bilinen sezgisel yöntemler — güvenlik kontrolü değil, segment alanı), ön plan süresi (usageDuration; uygulama arka plana geçince biriktirilir, sonraki pingle gider) ve son bilinen konum — yalnızca uygulamanız konum iznine zaten sahipse. SDK konum izni istemez, izin yoksa location anahtarını hiç göndermez; istemci IP'si sunucuda istekten alınır.

setEmail / setPhone iletişim kanallarını tag gibi kullanıcıya yazar. Bu kanallara gönderim yapılmaz; OneSignal importunda veri kaybolmasın ve segment "e-postası var" diyebilsin diye tutulur. Telefon E.164 biçimindedir; null değeri siler.

Expo config plugin​

{
"expo": {
"ios": { "bundleIdentifier": "com.acme.app" },
"android": { "googleServicesFile": "./google-services.json" },
"plugins": [
["@opennotification/react-native", {
"endpoint": "https://push.example.com",
"androidSmallIconPath": "./assets/ic_notification.png"
}]
]
}
}

npx expo prebuild (ya da EAS build) aşağıdaki elle kurulumun listelediği her şeyi uygular:

PlatformPlugin ne yapar
iOSaps-environment entitlement'ı, remote-notification arka plan modu, dört AppDelegate callback'i, Info.plist'inde OpenNotificationApiUrl = endpoint olan bir NotificationService extension hedefi.
AndroidPOST_NOTIFICATIONS izni, androidSmallIconPath'i res/drawable/ic_notification.png'ye kopyalar. google-services.json ve Gradle eklentisi Expo'nun kendi android.googleServicesFile'ından gelir.
SeçenekVarsayılan
endpoint—Extension için API taban URL'si.
iosServiceExtensiontrueExtension'ı atlamak için false (o zaman iOS'ta delivered yok).
iosServiceExtensionNameNotificationServiceHedef adı; bundle id <bundleIdentifier>.<ad>.
iosDeploymentTargetuygulamanınki
iosApsEnvironmentdevelopmentEAS build sırasında doğrusunu koyar.
androidSmallIconPath—Tek renkli PNG, saydam üzerine beyaz.
androidSmallIconic_notificationYukarıdaki PNG'nin drawable adı.

Sizde kalanlar: extension'ın App ID'si ve profili (com.acme.app.NotificationService) — ya da extra.eas.build.experimental.ios.appExtensions ile EAS'a bırakın — ve .p8 yüklemesi (iOS platform kurulumu). Plugin Expo SDK 53+'ın Swift AppDelegate'ini yamalar ve aynı bildirim delegate'ini sahiplenen expo-notifications ile birlikte çalışmaz.

Elle kurulum (bare React Native)​

Android​

1 android/app/ içinde google-services.json ve Gradle eklentisi — Android platform kurulumu. Firebase Messaging paketin Gradle modülüyle gelir; dependencies'e bir şey eklemeyin.

2 android/app/src/main/res/drawable/ic_notification.png konumunda tek renkli durum çubuğu simgesi (saydam üzerine beyaz), androidSmallIcon olarak verilir. Android başka her şeyi gri kare çizer.

3 Android 13+: requestPermission() POST_NOTIFICATIONS ister; izni modülün manifest'i bildirir.

Autolinking modülü bir sonraki build'de alır. Zaten bir FirebaseMessagingService'iniz var mı? onNewToken ve onMessageReceived'i Kotlin SDK'nın anlattığı gibi iletin — aynı kod.

iOS​

1 cd ios && pod install.

2 Xcode → uygulama hedefi → Signing & Capabilities → Push Notifications ve Background Modes → Remote notifications ekleyin.

3 AppDelegate'ten dört callback'i iletin. Swift:

import OpenNotification
import UserNotifications

// application(_:didFinishLaunchingWithOptions:) içinde
UNUserNotificationCenter.current().delegate = self
OpenNotification.setLaunchNotification(launchOptions?[.remoteNotification] as? [AnyHashable: Any])

func application(_ application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
OpenNotification.didRegister(deviceToken: deviceToken)
}
func application(_ application: UIApplication,
didFailToRegisterForRemoteNotificationsWithError error: Error) {
OpenNotification.didFailToRegister(error: error)
}

extension AppDelegate: UNUserNotificationCenterDelegate {
func userNotificationCenter(_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completionHandler: @escaping () -> Void) {
OpenNotification.didReceive(response: response)
completionHandler()
}
func userNotificationCenter(_ center: UNUserNotificationCenter,
willPresent notification: UNNotification,
withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
OpenNotification.willPresent(notification: notification)
completionHandler(OpenNotification.presentationOptions(for: notification))
}
}

Objective-C AppDelegate.mm: #import "YourApp-Swift.h" ve aynı dört OpenNotification sınıf metodunu çağırın.

Bunlar olmadan izin verilir, token hiç gelmez ve requestPermission() no_token ile döner.

4 Notification Service Extension — iOS'ta delivered, görsel ve buton için zorunlu:

  1. File → New → Target… → Notification Service Extension, adı NotificationService, deployment target = uygulamanınki.
  2. NotificationService.swift'ini node_modules/@opennotification/react-native/ios/NotificationServiceExtension/NotificationService.swift ile değiştirin.
  3. Extension'ın Info.plist'ine String OpenNotificationApiUrl = API taban URL'niz ekleyin.
  4. Kendi App ID / profilini verin (com.acme.app.NotificationService).

5 .p8'i yükleyin — iOS platform kurulumu.

Ne neyi bildirir​

OlayiOSAndroid
deliveredNotification Service ExtensionFirebaseMessagingService (native)
openeddidReceive response → native modülNotificationReceiver (native)
clicked (buton)action identifier'lı didReceivebuton id'li NotificationReceiver
dismissediOS'ta yokNotificationReceiver (native)

Android'de her ping native gönderilir — FCM süreci içinde JavaScript olmadan uyandırabilir — JavaScript istemcisi olayları yalnızca dinleyicilerinize iletir. iOS'ta açılmaları istemci kendisi bildirir.

Notlar​

  • Mesajlar normalize edilir: APNs on bloğu ve FCM düz data, ikisi de tek OpenNotificationMessage olarak gelir.
  • @opennotification/core'dan yalnızca tipler içe aktarılır — sunucudan hiçbir şey bundle'ınıza girmez.
  • Abonelik kimliği UserDefaults / SharedPreferences'ta durur. Uygulama kalıcılığı kendi yönetmek isterse createClient'a kendi storage'ınızı verin; hiç native modül yokken (testler) bellekte kalır ve cihaz bir sonraki açılışta yeniden kaydolur, bu da aynı satırı token'a göre upsert eder.