So unterstützen Sie den direkten Push mit FCM-/APNs-Tokens

Anwendungsszenarien

Dieser Artikel ist für Sie relevant, wenn Ihre App folgende Merkmale aufweist:

• Die App ist bereits direkt an Google FCM und iOS APNs angebunden, hält eigene FCM- und APNs-Tokens und versendet Pushes eigenständig über die nativen Protokolle;
• Ältere App-Versionen haben das EngageLab AppPush SDK nicht integriert, sodass viele Bestandsnutzer keine EngageLab-registration_id besitzen und über die Push-Erstellungs-API nicht erreicht werden können;
• Sie möchten diese Bestandsnutzer zunächst ohne erzwungenes App-Update in das EngageLab-Push-System aufnehmen und anschließend schrittweise auf das SDK migrieren.

Lösungsüberblick

EngageLab stellt für dieses Szenario die Geräteregistrierungs-API bereit: Ihr Server übermittelt direkt die bereits vorhandenen FCM-Tokens oder APNs-Device-Tokens, und EngageLab erzeugt für jedes Token eine eindeutig zugeordnete registration_id. Anschließend können Sie – genau wie bei per SDK registrierten Nutzern – über die Push-Erstellungs-API Nachrichten per registration_id zustellen und registration_id-basierte Funktionen wie Tags, Aliase und Statistiken nutzen.

flowchart LR
    token["Ihre vorhandenen<br/>FCM- / APNs-Tokens"]
    register["Geräteregistrierungs-API<br/>/v4/devices/token/registration_id"]
    regId["registration_id"]
    push["Push-Erstellungs-API<br/>/v4/push"]
    device["Gerät des Nutzers<br/>empfängt die Benachrichtigung"]

    token --> register --> regId --> push --> device

Integrationsschritte:

1. Ihr Server ruft die Geräteregistrierungs-API auf, übermittelt Tokens plattformweise in Batches (1–500 pro Aufruf) und speichert die Zuordnung zwischen der zurückgegebenen registration_id und dem jeweiligen Token;
2. Beim Versand tragen Sie die registration_id der Zielnutzer in to.registration_id der Push-Erstellungs-API ein;
3. Ändert sich ein Token (FCM onNewToken, erneute APNs-Registrierung), rufen Sie die Geräteregistrierungs-API erneut auf, um die neue registration_id zu erhalten.

Eine häufige Frage nach der Integration lautet: Öffnet die App nach dem Antippen der Benachrichtigung die Startseite, oder kann sie direkt zu einer Zielseite wie den Bestelldetails springen? Im Folgenden wird dies am Beispiel von Android FCM erläutert.

Navigation beim Benachrichtigungsklick: Fazit

Das Öffnen einer Zielseite ist möglich, steht aber nicht automatisch zur Verfügung, nur weil eine registration_id registriert wurde.

• Standardmäßig öffnet ein Tipp auf die Benachrichtigung lediglich die App;
• Welche Seite konkret geöffnet wird, entscheidet die Klickverarbeitung Ihrer eigenen App;
• Um zu einer Zielseite zu springen, muss der Server in der Push-Anfrage intent.url angeben und Ihre App eine Activity bereitstellen, die auf diese Action reagieren kann.

Die Geräteregistrierungs-API stellt lediglich die Zuordnung zwischen FCM-Token und registration_id her; sie fügt Ihrer App keinerlei Navigationsfunktion hinzu, und diese Nutzer durchlaufen auch nicht die vom EngageLab SDK abhängige Klick-Weiterleitungslogik. Es handelt sich daher um eine Übergangslösung; langfristig empfehlen wir weiterhin die Migration auf das EngageLab AppPush SDK, siehe Abschnitt „Langfristige Empfehlung“ am Ende dieses Artikels.

Standardverhalten: keine Klickaktion konfiguriert

Wenn in der Push-Anfrage kein notification.android.intent konfiguriert ist, enthält die von EngageLab an FCM übermittelte Benachrichtigung keine click_action. Das Klickverhalten folgt dann vollständig dem FCM-Standardverhalten:

• Befindet sich die App im Hintergrund oder wurde sie beendet, zeigt FCM die Benachrichtigung automatisch an; ein Tipp öffnet die Start-Activity der App (die in AndroidManifest.xml als MAIN/LAUNCHER deklarierte Activity);
• Ob der Endnutzer die Startseite, die Anmeldeseite oder die zuvor geöffnete Seite sieht, hängt von der Startlogik Ihrer App und dem aktuellen Zustand des Task-Stacks ab.

„Standardmäßig App öffnen“ ist daher nicht gleichbedeutend mit „immer zur Startseite zurückkehren“. Details finden Sie in der offiziellen Firebase-Dokumentation: Nachrichten in einer Android-App empfangen.

Zielseite öffnen: intent.url → click_action

Zuordnungskette

Der EngageLab-Server bildet den Wert von notification.android.intent.url aus der Push-Erstellungs-API auf das Feld android.notification.click_action der FCM-Benachrichtigung ab; anschließend sucht das Android-System in Ihrer App nach einer Activity, die zu dieser Action passt.

flowchart LR
    pushApi["Push-Erstellungs-API<br/>notification.android.intent.url"]
    fcm["FCM-Nachricht<br/>android.notification.click_action"]
    activity["Ihre App<br/>Activity, die zur Action passt"]
    target["Fachliche Zielseite<br/>(z. B. Bestelldetails)"]

    pushApi --> fcm --> activity --> target

Die offizielle Definition von click_action finden Sie unter FCM AndroidNotification.

Schritt 1: Der Server gibt intent.url in der Push-Anfrage an

Fügen Sie beim Versand per registration_id unter notification.android das Feld intent.url hinzu und übergeben Sie fachliche Parameter über extras:

              
              curl -X POST https://pushapi-sgp.engagelab.com/v4/push \
  -u "appKey:masterSecret" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "push",
    "to": {
      "registration_id": ["13065ffa4e1a6cc91c3"]
    },
    "body": {
      "platform": "android",
      "notification": {
        "android": {
          "title": "Bestellung versendet",
          "alert": "Ihre Bestellung 20260911001 wurde versendet. Tippen Sie, um die Sendung zu verfolgen",
          "intent": {
            "url": "intent:#Intent;action=com.example.app.ORDER_DETAIL;component=com.example.app/com.example.app.OrderDetailActivity;end"
          },
          "extras": {
            "order_id": "20260911001",
            "page": "order_detail"
          }
        }
      }
    },
    "request_id": "order-shipped-20260911001"
  }'

            

Zum Wert von intent.url ist zu beachten:

• Es handelt sich um das Android-Intent-URI-Format (intent:#Intent;...;end), nicht um eine beliebige Webadresse;
• action ist der von Ihrer App definierte Aktionsname, component entspricht Paketname/vollqualifizierter Activity-Klassenname;
• Innerhalb derselben url kann nur action oder nur component angegeben werden; empfohlen wird jedoch die Angabe beider Werte, um die Ziel-Activity exakt zu treffen;
• Weitere Wertetypen (Startseite öffnen, Deeplink usw.) finden Sie in der Beschreibung von intent in den android-Benachrichtigungsfeldern der Push-Erstellungs-API.

Schritt 2: Ihre App stellt eine passende Activity bereit

Deklarieren Sie in AndroidManifest.xml für die Ziel-Activity einen intent-filter, dessen action mit der in intent.url übereinstimmt:

              
              <activity
    android:name=".OrderDetailActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="com.example.app.ORDER_DETAIL" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

            

Nachdem FCM die Benachrichtigung angezeigt hat und diese angetippt wurde, wird die entsprechende Activity mit dieser Action gestartet, und die Schlüssel-Wert-Paare aus den extras der Benachrichtigung werden in die Intent-Extras übernommen. Die Ziel-Activity liest die Parameter aus und führt das fachliche Routing durch:

              
              class OrderDetailActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val orderId = intent.getStringExtra("order_id")
        if (orderId.isNullOrEmpty()) {
            // Bei fehlendem Parameter auf die Bestellliste oder Startseite zurückfallen
            startActivity(Intent(this, MainActivity::class.java))
            finish()
            return
        }
        showOrderDetail(orderId)
    }
}

            

Verfügt Ihre App bereits über eine zentrale Routing-Seite (z. B. gelangen alle Benachrichtigungsklicks zunächst in eine PushRouterActivity, die anhand der Parameter an die konkreten Seiten verteilt), können Sie den component in intent.url auf diese Zwischenseite richten. Diese liest die extras aus und navigiert dann zur fachlichen Seite wie den Bestelldetails, sodass Sie nicht für jede fachliche Seite eine eigene Action deklarieren müssen.

Hinweise

• Muss das EngageLab SDK integriert werden? Nein. Die obige Kette hängt nur vom click_action-Mechanismus von FCM und den Activity-Deklarationen Ihrer eigenen App ab.
• Vorhandene click_action-Verarbeitung ist wiederverwendbar: Hat Ihre App bereits beim direkten Versand über FCM eine click_action-Verarbeitung implementiert, tragen Sie einfach den ursprünglichen Action-Wert in intent.url ein.
• Fehlende click_action-Verarbeitung muss ergänzt werden: Verlässt sich Ihre App derzeit nur auf das Standard-Öffnungsverhalten, müssen Sie gemäß „Schritt 2“ die Activity-Deklaration und die Parameterauswertung hinzufügen; andernfalls findet das System keine reagierende Activity, selbst wenn der Server intent.url konfiguriert.
• Fachliche Parameter über extras übergeben: intent.url bestimmt, „welche Seite geöffnet wird“; die auf der Seite anzuzeigenden Inhalte sollten über extras (z. B. order_id) übergeben und von der Ziel-Activity ausgewertet werden.
• Verhalten bei App im Vordergrund: Befindet sich die App im Vordergrund, zeigt FCM die Benachrichtigung nicht automatisch an, sondern ruft onMessageReceived Ihrer App auf; ob eine Benachrichtigung angezeigt wird und wie beim Klick navigiert wird, liegt vollständig bei Ihrer App.
• Verifikation: Verwenden Sie beim Integrationstest zunächst intent:#Intent;action=android.intent.action.MAIN;end, um die Funktionsfähigkeit der Kanalkette zu bestätigen, und ersetzen Sie den Wert anschließend durch Ihre fachliche Action, um die Navigation zur Zielseite zu prüfen.

Langfristige Empfehlung: Migrieren Sie möglichst bald auf das EngageLab AppPush SDK

Die Geräteregistrierungs-API ist als Kompatibilitäts- und Übergangslösung konzipiert: Sie ermöglicht es, Bestandsnutzer älterer App-Versionen ohne SDK-Integration zu erreichen, und erzeugt eine zugeordnete registration_id als Vorbereitung für die spätere Nutzung weiterer EngageLab-AppPush-Funktionen. Sie löst die Frage „Kann zugestellt werden?“ und ersetzt nicht das SDK.

Wir empfehlen, sie als Teil Ihrer Migrationsstrategie und nicht als Dauerlösung zu betrachten:

• Neue App-Versionen integrieren das EngageLab AppPush SDK: Neue Nutzer erhalten ihre registration_id über die Standardregistrierung des SDK und profitieren direkt von den vollständigen Funktionen zur Benachrichtigungsanzeige und Klickverarbeitung.
• Alte App-Versionen überbrücken mit direkten Tokens: Bestandsnutzer werden weiterhin über die per Geräteregistrierungs-API registrierte registration_id erreicht; beide Systeme können nebeneinander bestehen und müssen nicht zwangsweise zusammengeführt werden.
• Schrittweise Konvergenz mit Versionsupdates: Mit dem Umstieg der Nutzer auf SDK-Versionen nimmt die Zahl der Direkt-Token-Nutzer natürlich ab, bis schließlich alles im SDK-System vereinheitlicht ist.

Im Vergleich zum in diesem Artikel beschriebenen direkten Weg gilt nach der SDK-Integration:

• Die Navigation beim Benachrichtigungsklick wird einheitlich vom SDK verarbeitet; die drei von intent.url unterstützten Typen (bestimmte Activity, App-Startseite, Deeplink) erfordern keine einzelne Deklaration von Actions und Auswertungslogik auf App-Seite;
• Benachrichtigungsanzeige im Vordergrund, Benachrichtigungsstile (builder_id, style, channel_id usw.), Badges, Nachrichtengruppierung und weitere Felder entfalten ihre volle Wirkung;
• Das SDK meldet Geräteinformationen und Verhalten wie Klicks automatisch, sodass die Zustell- und Klickstatistiken in der Konsole vollständiger sind.

Zur Integration siehe die Android SDK-Integrationsanleitung und die iOS SDK-Integrationsanleitung.