Fehlerbehebung für Push-Benachrichtigungen

Den Braze/APNs-Workflow verstehen

Der Apple Push Notification Service (APNs) ist die Infrastruktur zum Senden von Push-Benachrichtigungen an Anwendungen, die auf Apple-Plattformen laufen. Hier ist die vereinfachte Struktur, wie Push-Benachrichtigungen für die Geräte Ihrer Nutzer:innen aktiviert werden und wie Braze Push-Benachrichtigungen an sie senden kann:

1. Sie konfigurieren das Push-Zertifikat und das Bereitstellungsprofil
2. Geräte registrieren sich bei APNs und stellen Braze Push-Token bereit
3. Sie starten eine Braze-Push-Campaign
4. Braze entfernt ungültige Token

Schritt 1: Push-Zertifikat und Bereitstellungsprofil konfigurieren

Um Ihre App zu entwickeln, erstellen Sie ein SSL-Zertifikat, um Push-Benachrichtigungen zu aktivieren. Dieses Zertifikat ist im Bereitstellungsprofil enthalten, mit dem Ihre App erstellt wird, und muss auch in das Braze-Dashboard hochgeladen werden. Das Zertifikat ermöglicht Braze, APNs mitzuteilen, dass es berechtigt ist, Push-Benachrichtigungen in Ihrem Namen zu senden.

Es gibt zwei Arten von Bereitstellungsprofilen und Zertifikaten: Entwicklung und Distribution. Wir empfehlen, nur Distribution-Profile und -Zertifikate zu verwenden, um Verwechslungen zu vermeiden. Wenn Sie sich für unterschiedliche Profile und Zertifikate für Entwicklung und Distribution entscheiden, stellen Sie sicher, dass das im Dashboard hochgeladene Zertifikat mit dem aktuell verwendeten Bereitstellungsprofil übereinstimmt.

Warnung

Ändern Sie nicht die Umgebung des Push-Zertifikats (Entwicklung versus Produktion). Das Ändern des Push-Zertifikats auf die falsche Umgebung kann dazu führen, dass Push-Token Ihrer Nutzer:innen versehentlich entfernt werden, sodass sie per Push nicht mehr erreichbar sind.

Schritt 2: Geräte registrieren sich bei APNs und stellen Braze Push-Token bereit

Wenn Nutzer:innen Ihre App öffnen, werden sie aufgefordert, Push-Benachrichtigungen zu akzeptieren. Wenn sie diese Aufforderung akzeptieren, generiert APNs ein Push-Token für dieses bestimmte Gerät. Das Swift SDK sendet das Push-Token sofort und asynchron für Apps, die die standardmäßige automatische Flush-Richtlinie verwenden. Nachdem wir ein Push-Token mit Nutzer:innen verknüpft haben, werden sie im Dashboard in ihrem Nutzerprofil unter dem Tab Engagement als „Push Registered“ angezeigt und sind berechtigt, Push-Benachrichtigungen aus Braze-Campaigns zu empfangen.

Hinweis

Ab macOS 13 können Sie auf bestimmten Geräten Push-Benachrichtigungen in einem iOS 16 Simulator unter Xcode 14 testen. Weitere Informationen finden Sie in den Xcode 14 Release Notes.

Überlegungen zur Push-Token-Generierung

• Wenn Nutzer:innen Ihre App auf einem anderen Gerät installieren, erstellt und erfasst Braze ein weiteres Token auf die gleiche Weise.
• Wenn Nutzer:innen Ihre App neu installieren, generiert das SDK ein neues Token und übergibt es an Braze. APNs und Braze können jedoch das ursprüngliche Token noch als gültig protokollieren.
• Wenn Nutzer:innen Ihre App deinstallieren, erhält Braze nicht sofort eine Benachrichtigung, und das Token erscheint weiterhin als gültig, bis APNs es außer Betrieb nimmt.
• Irgendwann nimmt APNs alte Token außer Betrieb. Braze hat darüber keine Kontrolle und keine Einsicht.

Schritt 3: Eine Braze-Push-Campaign starten

Wenn eine Push-Campaign gestartet wird, sendet Braze Anfragen an APNs, um Ihre Nachricht zuzustellen. Konkret werden die Anfragen für jedes aktuell gültige Push-Token an APNs übergeben, es sei denn, An das neueste Gerät der/des Nutzer:in senden ist ausgewählt. Nachdem Braze eine erfolgreiche Antwort von APNs erhalten hat, protokolliert Braze eine erfolgreiche Zustellung im Nutzerprofil, obwohl die/der Nutzer:in die tatsächliche Nachricht möglicherweise aus folgenden Gründen nicht erhalten hat:

• Das Gerät ist ausgeschaltet.
• Das Gerät ist nicht mit dem Internet verbunden (WLAN oder Mobilfunk).
• Die App wurde kürzlich deinstalliert.

Braze verwendet das im Dashboard hochgeladene SSL-Push-Zertifikat, um sich zu authentifizieren und zu verifizieren, dass es berechtigt ist, Push-Benachrichtigungen an die bereitgestellten Push-Token zu senden. Wenn ein Gerät online ist, sollte die Benachrichtigung kurz nach dem Senden der Campaign empfangen werden. Beachten Sie, dass Braze das standardmäßige APNs-Ablaufdatum für Benachrichtigungen auf 30 Tage setzt.

Schritt 4: Ungültige Token entfernen

Wenn APNs uns mitteilt, dass Push-Token, an die wir eine Nachricht senden wollten, ungültig sind, entfernen wir diese Token aus den Nutzerprofilen, mit denen sie verknüpft waren.

Hinweis

Es ist normal, dass APNs zunächst einen Erfolgsstatus zurückgibt, auch wenn ein Token nicht mehr registriert ist, da APNs Token-Invalidierungsereignisse nicht sofort meldet. APNs verzögert absichtlich die Rückgabe eines 410-Status für ungültige Token nach einem zufälligen Zeitplan, der den Schutz der Privatsphäre der Nutzer:innen gewährleisten und das Tracking von App-Deinstallationen verhindern soll. Sie können weiterhin Benachrichtigungen an ein nicht registriertes Token senden, bis APNs einen 410-Status zurückgibt.

Push-Fehler überprüfen

Messaging Observability zeigt, warum ein Push aus einer Campaign oder einem Canvas nicht gesendet wurde, einschließlich Fehler, die von APNs oder FCM zurückgegeben wurden.

Häufige Fehler umfassen nutzerspezifische Benachrichtigungen wie „Received Unregistered Sending to Push Token“.

Darüber hinaus bietet Braze auch ein Push-Changelog im Nutzerprofil unter dem Tab Engagement. Dieses Changelog bietet Einblick in das Push-Registrierungsverhalten, wie z. B. Token-Invalidierung, Push-Registrierungsfehler, Token, die zu neuen Nutzer:innen verschoben werden, usw.

Push-Benachrichtigungsfehler

Received Unregistered Sending to Push Token

• Stellen Sie sicher, dass das Push-Token, das über die Methode AppDelegate.braze?.notifications.register(deviceToken:) an Braze gesendet wird, gültig ist. Überprüfen Sie den Fehler für die Campaign oder den Canvas in Messaging Observability. Das Token sollte in etwa so aussehen: 6e407a9be8d07f0cdeb9e724733a89445f57a89ec890d63867c482a483506fa6, ein langer String aus einer Mischung von Buchstaben und Zahlen. Wenn Ihr Push-Token anders aussieht, überprüfen Sie Ihren Code zum Senden der Push-Token an Braze.
• Stellen Sie sicher, dass Ihr Push-Bereitstellungsprofil mit der Umgebung übereinstimmt, in der Sie testen. Universelle Zertifikate können im Braze-Dashboard so konfiguriert werden, dass sie entweder an die Entwicklungs- oder Produktions-APNs-Umgebung senden. Die Verwendung eines Entwicklungszertifikats für eine Produktions-App oder eines Produktionszertifikats für eine Entwicklungs-App funktioniert nicht.
• Überprüfen Sie, ob das bei Braze hochgeladene Push-Token mit dem Bereitstellungsprofil übereinstimmt, das zum Erstellen der App verwendet wurde, von der das Push-Token gesendet wurde.

Device Token Not for Topic

APNs gibt DeviceTokenNotForTopic (HTTP-Status 400) zurück, wenn das Push-Token nicht mit dem Topic (Bundle-ID) übereinstimmt, der für Ihre Zugangsdaten konfiguriert ist. Überprüfen Sie den Fehler für die Campaign oder den Canvas in Messaging Observability.

Um die Nichtübereinstimmung zu beheben:

1. Bestätigen Sie, dass die Bundle-ID der App mit der App-Bundle-ID in Braze übereinstimmt (Einstellungen > App-Einstellungen > Push-Benachrichtigungseinstellungen).
2. Überprüfen Sie, ob das Bereitstellungsprofil, das zum Erstellen der App verwendet wurde, die Push-Fähigkeit für diese Bundle-ID enthält.
3. Bestätigen Sie, dass die in Braze hochgeladenen Push-Zugangsdaten mit der Umgebung der App übereinstimmen (Entwicklung vs. Produktion).
4. Überprüfen Sie bei .p8-Schlüsseln, ob Team-ID und Key-ID in Braze mit Ihrem Apple Developer-Konto übereinstimmen.
5. Laden Sie einen gültigen .p8-Schlüssel oder ein .p12-Zertifikat erneut hoch, wenn die Zugangsdaten rotiert oder widerrufen wurden.

Bevorzugen Sie nach Möglichkeit .p8-Authentifizierungsschlüssel. Informationen zu Zugangsdatentypen und Dashboard-Statusanzeigen finden Sie unter Zu einem .p8-Authentifizierungsschlüssel migrieren.

BadDeviceToken beim Senden an Push-Token

BadDeviceToken ist ein APNs-Fehlercode und stammt nicht von Braze. Es kann verschiedene Gründe geben, warum diese Antwort zurückgegeben wird, darunter:

• Die App hat ein Push-Token erhalten, das für die im Dashboard hochgeladenen Zugangsdaten ungültig war.
• Push wurde für diesen Workspace deaktiviert.
• Die Nutzer:in hat Push deaktiviert.
• Die App wurde deinstalliert.
• Apple hat das Push-Token aktualisiert, wodurch das alte Token ungültig wurde.
• Die App wurde für eine Produktionsumgebung erstellt, aber die in Braze hochgeladenen Push-Zugangsdaten sind für eine Entwicklungsumgebung konfiguriert (oder umgekehrt).

Probleme mit der Push-Registrierung

Keine Aufforderung zur Push-Registrierung

Wenn die Anwendung Sie nicht zur Registrierung für Push-Benachrichtigungen auffordert, liegt wahrscheinlich ein Problem mit Ihrer Push-Registrierungsintegration vor. Stellen Sie sicher, dass Sie unserer Dokumentation gefolgt sind und unsere Push-Registrierung korrekt integriert haben. Sie können auch Breakpoints in Ihrem Code setzen, um sicherzustellen, dass der Push-Registrierungscode ausgeführt wird.

Keine „Push Registered“-Nutzer:innen im Dashboard angezeigt (vor dem Senden von Nachrichten)

Stellen Sie sicher, dass Ihre App korrekt konfiguriert ist, um Push-Benachrichtigungen zuzulassen. Häufige Fehlerquellen, die Sie überprüfen sollten:

• Überprüfen Sie, ob Ihre App Sie auffordert, Push-Benachrichtigungen zuzulassen. Typischerweise erscheint diese Aufforderung beim ersten Öffnen der App, kann aber auch an anderer Stelle programmiert werden. Wenn sie nicht dort erscheint, wo sie sollte, liegt das Problem wahrscheinlich in der grundlegenden Konfiguration der Push-Funktionen Ihrer App.
  • Überprüfen Sie, ob die Schritte für die Push-Integration erfolgreich abgeschlossen wurden.
  • Überprüfen Sie, ob das Bereitstellungsprofil, mit dem Ihre App erstellt wurde, Berechtigungen für Push enthält. Stellen Sie sicher, dass Sie alle verfügbaren Bereitstellungsprofile aus Ihrem Apple Developer-Konto abrufen. Um dies zu bestätigen, führen Sie die folgenden Schritte aus:
    1. Navigieren Sie in Xcode zu Preferences > Accounts (oder verwenden Sie die Tastenkombination Command+,).
    2. Wählen Sie die Apple-ID aus, die Sie für Ihr Entwicklerkonto verwenden, und klicken Sie auf View Details.
    3. Klicken Sie auf der nächsten Seite auf Refresh und bestätigen Sie, dass Sie alle verfügbaren Bereitstellungsprofile abrufen.
• Überprüfen Sie, ob Sie die Push-Funktion in Ihrer App korrekt aktiviert haben.
• Überprüfen Sie, ob Ihr Push-Bereitstellungsprofil mit der Umgebung übereinstimmt, in der Sie testen. Universelle Zertifikate können im Braze-Dashboard so konfiguriert werden, dass sie entweder an die Entwicklungs- oder Produktions-APNs-Umgebung senden. Die Verwendung eines Entwicklungszertifikats für eine Produktions-App oder eines Produktionszertifikats für eine Entwicklungs-App funktioniert nicht.
• Überprüfen Sie, ob Sie unsere Methode registerPushToken aufrufen, indem Sie einen Breakpoint in Ihrem Code setzen.
• Stellen Sie sicher, dass Sie mit einem Gerät testen (Push funktioniert nicht auf einem Simulator) und eine gute Netzwerkverbindung haben.

Push-Benachrichtigungen gesendet, aber nicht auf Geräten der Nutzer:innen angezeigt

„Push Registered“-Nutzer:innen sind nach dem Senden von Nachrichten nicht mehr aktiviert

Dies deutet wahrscheinlich darauf hin, dass die/der Nutzer:in ein ungültiges Push-Token hatte. Dies kann aus mehreren Gründen passieren:

Nichtübereinstimmung von Dashboard- und App-Zertifikat

Wenn das im Dashboard hochgeladene Push-Zertifikat nicht mit dem im Bereitstellungsprofil übereinstimmt, mit dem Ihre App erstellt wurde, lehnt APNs das Token ab. Überprüfen Sie, ob Sie das richtige Zertifikat hochgeladen haben, und schließen Sie eine weitere Sitzung in der App ab, bevor Sie eine weitere Testbenachrichtigung versuchen.

Anwendung wurde deinstalliert

Wenn Nutzer:innen Ihre Anwendung deinstalliert haben, wird ihr Push-Token ungültig und beim nächsten Senden entfernt.

Bereitstellungsprofil neu generieren

Als letzten Ausweg können Sie ein komplett neues Bereitstellungsprofil erstellen, um Konfigurationsfehler zu beheben, die durch die Arbeit mit mehreren Umgebungen, Profilen und Apps gleichzeitig entstehen. Es gibt viele „bewegliche Teile“ bei der Einrichtung von Push-Benachrichtigungen, daher ist es manchmal am besten, von vorne zu beginnen. Dies hilft auch, das Problem einzugrenzen, wenn Sie die Fehlerbehebung fortsetzen müssen.

Nachrichten werden nicht an „Push Registered“-Nutzer:innen zugestellt

App ist im Vordergrund

Bei iOS-Versionen, die Push nicht über das UserNotifications-Framework integrieren, wird die Push-Nachricht nicht angezeigt, wenn die App im Vordergrund ist, wenn sie empfangen wird. Sie sollten die App auf Ihren Testgeräten in den Hintergrund versetzen, bevor Sie Testnachrichten senden.

Testbenachrichtigung falsch geplant

Überprüfen Sie den Zeitplan, den Sie für Ihre Testnachricht festgelegt haben. Wenn er auf Zustellung nach Ortszeit oder intelligentes Timing eingestellt ist, haben Sie die Nachricht möglicherweise noch nicht erhalten (oder die App war im Vordergrund, als sie empfangen wurde).

Nutzer:in nicht „Push Registered“ für die getestete App

Überprüfen Sie das Nutzerprofil der/des Nutzer:in, an die/den Sie eine Testnachricht senden möchten. Unter dem Tab Engagement sollte eine Liste von „pushfähigen Apps“ angezeigt werden. Überprüfen Sie, ob die App, an die Sie Testnachrichten senden möchten, in dieser Liste enthalten ist. Nutzer:innen werden als „Push Registered“ angezeigt, wenn sie ein Push-Token für eine beliebige App in Ihrem Workspace haben, sodass dies ein falsch positives Ergebnis sein könnte.

Folgendes würde auf ein Problem mit der Push-Registrierung hinweisen oder darauf, dass das Token der/des Nutzer:in nach dem Senden von APNs als ungültig an Braze zurückgegeben wurde:

Push-Klicks werden nicht protokolliert

• Stellen Sie sicher, dass Sie die Schritte zur Push-Integration befolgt haben.
• Braze verarbeitet keine Push-Benachrichtigungen, die im Vordergrund stillschweigend empfangen werden (standardmäßiges Vordergrund-Push-Verhalten vor dem UserNotifications-Framework). Das bedeutet, dass Links nicht geöffnet und Push-Klicks nicht protokolliert werden. Wenn Ihre Anwendung das UserNotifications-Framework noch nicht integriert hat, verarbeitet Braze keine Push-Benachrichtigungen, wenn der Anwendungsstatus UIApplicationStateActive ist. Stellen Sie sicher, dass Ihre App Aufrufe an Push-Verarbeitungsmethoden nicht verzögert; andernfalls behandelt das Swift SDK Push-Benachrichtigungen möglicherweise als stille Vordergrund-Push-Ereignisse und verarbeitet sie nicht.

Deeplinks funktionieren nicht

Umfassende Informationen zur Fehlerbehebung über alle Kanäle hinweg – einschließlich Universal Links, benutzerdefinierter Schemata, E-Mail und Drittanbieter wie Branch – finden Sie unter Fehlerbehebung für Deeplinks.

Web-Links aus Push-Klicks öffnen sich nicht

Links in Push-Benachrichtigungen müssen ATS-konform sein, um in Web-Views geöffnet werden zu können. Stellen Sie sicher, dass Ihre Web-Links HTTPS verwenden. Weitere Informationen finden Sie unter ATS-Konformität.

Deeplinks aus Push-Klicks öffnen sich nicht

Der größte Teil des Codes, der Deeplinks verarbeitet, verarbeitet auch Push-Öffnungen. Stellen Sie zunächst sicher, dass Push-Öffnungen protokolliert werden. Wenn nicht, beheben Sie dieses Problem (da die Lösung oft auch die Link-Verarbeitung behebt).

Wenn Öffnungen protokolliert werden, prüfen Sie, ob es sich um ein Problem mit dem Deeplink im Allgemeinen oder mit der Deeplink-Verarbeitung bei Push-Klicks handelt. Testen Sie dazu, ob ein Deeplink aus einem In-App-Nachricht-Klick funktioniert.

Tippen auf Push Story-Bilder bewirkt nichts

Wenn das Tippen auf ein Push Story-Bild nichts bewirkt, öffnen Sie die Info.plist der Notification Content Extension und bestätigen Sie, dass UNNotificationExtensionUserInteractionEnabled auf YES gesetzt ist. Das Swift SDK-Modul BrazePushStory benötigt diesen Schlüssel, damit die Extension Taps empfangen kann. Siehe Push Stories.