Integration für Projekte mit Firebase (FCM)

Dieser Leitfaden richtet sich an Teams, die in ihrer App bereits Firebase Cloud Messaging (FCM) nutzen – egal ob natives Android/iOS, Flutter, React Native Firebase oder Capacitor. Er zeigt, wie Sie NotiPilot hinzufügen, ohne Ihr bestehendes Firebase-Setup zu beeinträchtigen. Die allgemeine API-Referenz finden Sie in der Überblick.

Unterstützte Versionen: Firebase Android BoM 33+ · Firebase iOS SDK 10+ · firebase_messaging (Flutter) 15+ · @react-native-firebase/messaging 20+

#Das Einzige, was Sie wissen müssen

NotiPilot 1.0.0 stellt Benachrichtigungen über den Expo Push Service zu, und Expo nutzt unter Android FCM und unter iOS APNs. Ihre Firebase-Infrastruktur bleibt also unverändert; Sie müssen lediglich:

1. den vom Gerät erhaltenen nativen Token in einen Expo Push Token konvertieren,
2. diesen Token bei NotiPilot registrieren.

⚠️ Senden Sie unter iOS nicht den FCM-Token von Firebase. Da Expo unter iOS direkt über APNs zustellt, wird der rohe APNs-Token benötigt.

Sie können auch direkt einen FCM-Token (provider: "fcm") bei der API registrieren; das Gerät wird registriert und erscheint in Segmenten, in Version 1.0.0 werden an diese Geräte jedoch keine Benachrichtigungen zugestellt.

#1. Firebase- und Expo-Zugangsdaten (einmalig)

1. FCM-V1-Dienstkonto: Firebase-Konsole → Projekteinstellungen → Dienstkonten → Neuen privaten Schlüssel generieren. Bewahren Sie die heruntergeladene JSON-Datei auf.
2. APNs-Schlüssel (iOS): Vermutlich haben Sie bereits einen .p8-Schlüssel bei Firebase hochgeladen. Diesen können Sie wiederverwenden (falls nicht, finden Sie die Schritte zur Erstellung im iOS-Leitfaden).
3. Legen Sie auf expo.dev ein Projekt an und notieren Sie die Projekt-ID (UUID).
4. expo.dev → Projekt → Credentials:
   • Android → FCM V1 service account key → JSON aus Schritt 1
   • iOS → Bundle ID hinzufügen → Push Key → .p8 + Key ID + Team ID
5. Legen Sie Ihre App im NotiPilot-Dashboard an: Expo Project ID, Expo Access Token (expo.dev → Access Tokens), Android Package, iOS Bundle ID.

#2. Token-Konvertierung (derselbe HTTP-Request für alle Plattformen)

POST https://exp.host/--/api/v2/push/getExpoPushToken
Content-Type: application/json

{
  "type": "fcm",                        // Android: "fcm", iOS: "apns"
  "deviceId": "8f14e45f-ceea-467a-9575-0b3f5c6b2a11", // identisch mit device_uid (UUID in Kleinbuchstaben)
  "development": false,                 // true für iOS-Debug-Builds (APNs-Sandbox)
  "appId": "com.example.app",           // Android package / iOS bundle id
  "deviceToken": "<FCM- oder APNs-Token>",
  "projectId": "<Expo-Projekt-ID>"
}

Antwort:

{ "data": { "expoPushToken": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]" } }

Dieser Endpoint wird von Expos eigener Bibliothek expo-notifications verwendet und ist von Expo nicht gesondert dokumentiert.

#3. Registrierung bei NotiPilot

POST https://app.notipilot.com/api/v1/register-device
Content-Type: application/json

{
  "app_id": "<Expo-Projekt-ID>",
  "device_uid": "8f14e45f-ceea-467a-9575-0b3f5c6b2a11",
  "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "platform": "android",
  "provider": "expo",
  "attributes": { "locale": "tr", "country": "TR", "city": "Istanbul" }
}

#4. Integrationspunkte im bestehenden Firebase-Code

#Android — FirebaseMessagingService

override fun onNewToken(token: String) {
    // Ihr bestehender Code (z. B. Senden an Ihr eigenes Backend) kann unverändert bleiben
    scope.launch { NotiPilot.registerDevice(applicationContext, fcmToken = token) }
}

Vollständiger Code: Kotlin · Java

#iOS — APNs-Token über Firebase Messaging abrufen

import FirebaseMessaging

extension AppDelegate: MessagingDelegate {
    func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
        // FCM-Token wurde erneuert; für NotiPilot den APNs-Token verwenden
        guard let apnsToken = Messaging.messaging().apnsToken else { return }
        Task { try? await NotiPilot.shared.registerDevice(apnsToken: apnsToken) }
    }
}

Ist FirebaseAppDelegateProxyEnabled deaktiviert, stellen Sie sicher, dass Sie in didRegisterForRemoteNotificationsWithDeviceToken die Zuweisung Messaging.messaging().apnsToken = deviceToken vornehmen. Vollständiger Code: Swift · Objective-C

#Flutter — firebase_messaging

final token = Platform.isIOS
    ? await FirebaseMessaging.instance.getAPNSToken()
    : await FirebaseMessaging.instance.getToken();

Vollständiger Code: Flutter

#React Native — @react-native-firebase/messaging

const token = Platform.OS === 'ios'
  ? await messaging().getAPNSToken()
  : await messaging().getToken();

Vollständiger Code: React Native — Methode B

#5. Eingehende Benachrichtigungen auslesen

Expo sendet an Android über FCM mit den folgenden Feldern. Schreiben Sie Ihren Code so, dass er beide Varianten unterstützt:

Unter iOS kommen Titel und Text im Standardfeld aps.alert an; die benutzerdefinierten Daten liegen im Schlüssel userInfo["body"].

#6. Hinweise zur gemeinsamen Nutzung mit Firebase

• Sie können weiterhin über Ihr eigenes Backend per FCM senden; NotiPilot steht dem nicht im Weg.
• Damit Benachrichtigungen nicht doppelt ankommen, senden Sie dieselbe Kampagne nicht gleichzeitig über Ihr eigenes System und über NotiPilot.
• Das Firebase Web SDK (Web Push) wird in Version 1.0.0 nicht unterstützt.
• Unter Android 13+ ist die Berechtigung POST_NOTIFICATIONS, unter iOS die Zustimmung des Nutzers erforderlich (wenn Sie diese bereits über Firebase anfragen, ist nichts weiter zu tun).

#Checkliste

• JSON des FCM-V1-Dienstkontos und APNs-Schlüssel (.p8) in das Expo-Projekt hochgeladen
• Unter iOS wird der APNs-Token (nicht der FCM-Token) konvertiert
• In onNewToken / didReceiveRegistrationToken wird die NotiPilot-Registrierung erneuert
• Expo Project ID, Paketname und Bundle ID im Dashboard sind korrekt