Skip to content

Fehlerbehebung bei Deeplinking

Diese Seite behandelt häufige Probleme mit Deeplinking unter iOS und deren Diagnose. Hilfe bei der Auswahl des richtigen Linktyps finden Sie im iOS-Deeplinking-Leitfaden. Für Details zur Implementierung siehe Deeplinking.

Wenn ein Deeplink mit benutzerdefiniertem Schema (z. B. myapp://products/123) Ihre App öffnet, aber nicht zum gewünschten Bildschirm navigiert:

  1. Überprüfen Sie, ob das Schema registriert ist. Prüfen Sie in Xcode, ob Ihr Schema unter CFBundleURLTypes in Info.plist aufgeführt ist.
  2. Überprüfen Sie Ihren Handler. Setzen Sie einen Haltepunkt in application(_:open:options:), um zu bestätigen, dass die Methode aufgerufen wird, und inspizieren Sie den url-Parameter.
  3. Testen Sie den Link unabhängig. Führen Sie den folgenden Befehl im Terminal aus, um den Deeplink außerhalb von Braze zu testen: 
    1

    xcrun simctl openurl booted "myapp://products/123"

    Wenn der Link hier nicht funktioniert, liegt das Problem in der URL-Verarbeitung Ihrer App – nicht bei Braze.

  4. Überprüfen Sie das URL-Format. Stellen Sie sicher, dass die URL in Ihrer Campaign mit den Erwartungen Ihres Handlers übereinstimmt. Häufige Fehler sind fehlende Pfadkomponenten oder falsche Groß-/Kleinschreibung.

Wenn ein Universal Link (z. B. https://myapp.com/products/123) in Safari statt in Ihrer App geöffnet wird:

Überprüfen Sie die Associated-Domains-Berechtigung

Öffnen Sie in Xcode Ihr App-Ziel > Signing & Capabilities und prüfen Sie, ob applinks:yourdomain.com unter Associated Domains aufgeführt ist.

Validieren Sie die AASA-Datei

Ihre Apple App Site Association (AASA)-Datei muss an einem der folgenden Orte gehostet werden:

  • https://yourdomain.com/.well-known/apple-app-site-association
  • https://yourdomain.com/apple-app-site-association

Überprüfen Sie Folgendes:

  • Die Datei wird über HTTPS mit einem gültigen Zertifikat bereitgestellt.
  • Der Content-Type ist application/json.
  • Die Dateigröße liegt unter 128 KB.
  • Die appID stimmt mit Ihrer Team-ID und Bundle-ID überein (z. B. ABCDE12345.com.example.myapp).
  • Das paths- oder components-Array enthält die erwarteten URL-Muster.

Sie können Ihre AASA mit dem Suchvalidierungstool von Apple oder durch Ausführen des folgenden Befehls validieren:

1

swcutil dl -d yourdomain.com

Überprüfen Sie den AppDelegate

Stellen Sie sicher, dass application(_:continue:restorationHandler:) in Ihrem AppDelegate implementiert ist und die NSUserActivity korrekt verarbeitet:

1
2
3
4
5
6
7
8
9
10

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else {
    return false
  }
  // Handle the URL
  return true
}

Überprüfen Sie die Braze-SDK-Konfiguration

Wenn Sie Universal Links aus Push-Benachrichtigungen, In-App-Nachrichten oder Content Cards von Braze verwenden, stellen Sie sicher, dass forwardUniversalLinks aktiviert ist:

1
2

let configuration = Braze.Configuration(apiKey: "<BRAZE_API_KEY>", endpoint: "<BRAZE_ENDPOINT>")
configuration.forwardUniversalLinks = true

Überprüfen Sie das Problem mit langem Drücken

Wenn Sie einen Universal Link lange gedrückt halten und Öffnen auswählen, kann iOS die Universal-Link-Zuordnung für diese Domain „aufheben“. Dies ist ein bekanntes iOS-Verhalten. Um es zurückzusetzen, drücken Sie erneut lange auf den Link und wählen Sie In [App-Name] öffnen.

E-Mail-Links werden durch das Klick-Tracking-System Ihres ESP geleitet, das Links in eine Tracking-Domain einbettet (z. B. https://click.yourdomain.com/...). Damit Universal Links aus E-Mails funktionieren, müssen Sie die AASA-Datei auf Ihrer Klick-Tracking-Domain konfigurieren – nicht nur auf Ihrer primären Domain.

Überprüfen Sie die AASA der Klick-Tracking-Domain

  1. Identifizieren Sie Ihre Klick-Tracking-Domain in Ihren ESP-Einstellungen (SendGrid, SparkPost oder Amazon SES).
  2. Hosten Sie die AASA-Datei unter https://your-click-tracking-domain/.well-known/apple-app-site-association.
  3. Stellen Sie sicher, dass die AASA-Datei auf der Klick-Tracking-Domain dieselbe appID und gültige Pfadmuster enthält.

Für ESP-spezifische Einrichtungsanweisungen siehe Universal Links und App Links.

Überprüfen Sie die Weiterleitungskette

Einige ESPs führen eine Weiterleitung von der Klick-Tracking-URL zu Ihrer endgültigen URL durch. Universal Links funktionieren nur, wenn iOS die ursprüngliche Domain (die Klick-Tracking-Domain) als mit Ihrer App verknüpft erkennt. Wenn die Weiterleitung die AASA-Prüfung umgeht, wird der Link in Safari geöffnet.

Zum Testen:

  1. Senden Sie sich selbst eine Test-E-Mail.
  2. Halten Sie den Link gedrückt und inspizieren Sie die URL – dies ist die Klick-Tracking-URL.
  3. Überprüfen Sie, ob diese Domain eine gültige AASA-Datei hat.

Überprüfen Sie den BrazeDelegate

Wenn Sie BrazeDelegate.braze(_:shouldOpenURL:) implementieren, stellen Sie sicher, dass Links kanalübergreifend konsistent verarbeitet werden. Der context-Parameter enthält den Quellkanal. Prüfen Sie die bedingte Logik, die möglicherweise versehentlich Links aus bestimmten Kanälen herausfiltert.

Aktivieren Sie die ausführliche Protokollierung

Aktivieren Sie die ausführliche Protokollierung und reproduzieren Sie das Problem. Suchen Sie nach dem Opening-Protokolleintrag:

1
2
3
4

Opening '<URL>':
- channel: <SOURCE_CHANNEL>
- useWebView: <true/false>
- isUniversalLink: <true/false>

Vergleichen Sie die Protokollausgabe des funktionierenden Kanals mit der des nicht funktionierenden Kanals. Unterschiede bei useWebView oder isUniversalLink zeigen, wie das SDK den Link unterschiedlich interpretiert.

Überprüfen Sie angepasste Anzeige-Delegates

Wenn Sie einen angepassten In-App-Nachrichten-Anzeige-Delegaten oder einen Content-Card-Klick-Handler verwenden, stellen Sie sicher, dass dieser Link-Ereignisse korrekt an das Braze SDK zur Verarbeitung weiterleitet.

„Web-URL in App öffnen“ zeigt eine leere oder fehlerhafte Seite

Wenn die Auswahl von Open Web URL Inside App zu einer leeren oder fehlerhaften WebView führt:

  1. Überprüfen Sie, ob die URL HTTPS verwendet. Die WebView des SDK erfordert ATS-konforme URLs. HTTP-Links schlagen ohne Fehlermeldung fehl.
  2. Überprüfen Sie die Content-Security-Policy-Header. Wenn die Zielwebseite X-Frame-Options: DENY oder eine restriktive Content-Security-Policy setzt, wird die Darstellung in einer WebView blockiert.
  3. Überprüfen Sie Weiterleitungen zu benutzerdefinierten Schemata. Wenn die Webseite zu einem benutzerdefinierten Schema weiterleitet (z. B. myapp://), kann die WebView dies nicht verarbeiten.
  4. Testen Sie die URL in Safari. Wenn die Seite in Safari auf dem Gerät nicht geladen wird, wird sie auch in der WebView nicht geladen.

Fehlerbehebung bei Branch mit Braze

Wenn Sie Branch als Ihren Linking-Anbieter verwenden:

Überprüfen Sie, ob der BrazeDelegate an Branch weiterleitet

Ihr BrazeDelegate muss Branch-Links abfangen und an das Branch SDK weiterleiten. Überprüfen Sie Folgendes:

1
2
3
4
5
6
7
8
9

func braze(_ braze: Braze, shouldOpenURL context: Braze.URLContext) -> Bool {
  if let host = context.url.host, host.contains("app.link") {
    // Route to Branch SDK
    Branch.getInstance.handleDeepLink(context.url)
    return false
  }
  // Let Braze handle other links
  return true
}

Wenn shouldOpenURL für Branch-Links true zurückgibt, verarbeitet Braze diese direkt, anstatt sie an Branch weiterzuleiten.

Stellen Sie sicher, dass die Branch-Domain in Ihrem BrazeDelegate mit Ihrer tatsächlichen Branch-Link-Domain übereinstimmt. Branch verwendet mehrere Domain-Formate:

  • yourapp.app.link (Standard)
  • yourapp-alternate.app.link (alternativ)
  • Angepasste Domains (sofern im Branch-Dashboard konfiguriert)

Aktivieren Sie die Protokollierung beider SDKs

Um festzustellen, wo der Link in der Kette unterbrochen wird:

  1. Aktivieren Sie die ausführliche Protokollierung von Braze – suchen Sie nach Opening '<URL>':-Einträgen, um zu überprüfen, ob das SDK den Link erhalten hat.
  2. Aktivieren Sie den Branch-Testmodus – überprüfen Sie das Branch-Dashboard auf Link-Klick-Ereignisse.
  3. Aktivieren Sie die ausführliche Protokollierung von Braze. Suchen Sie nach Opening '<URL>':-Einträgen, um sicherzustellen, dass das SDK den Link erhalten hat.
  4. Aktivieren Sie den Branch-Testmodus. Überprüfen Sie das Branch-Dashboard auf Link-Klick-Ereignisse.
  5. Wenn Braze den Link protokolliert, Branch jedoch keinen Klick erkennt, liegt das Problem wahrscheinlich an der BrazeDelegate-Weiterleitungslogik.

Überprüfen Sie die Branch-Dashboard-Konfiguration

Überprüfen Sie im Branch-Dashboard Folgendes:

  • Die Bundle-ID und Team-ID Ihrer App stimmen mit Ihrem Xcode-Projekt überein.
  • Ihre Associated Domains enthalten die Branch-Link-Domain.
  • Ihre Branch-AASA-Datei ist gültig (Branch hostet diese automatisch auf app.link-Domains).

Testen Sie den Branch-Link außerhalb von Braze, um das Problem einzugrenzen:

  1. Öffnen Sie den Branch-Link in Safari auf Ihrem Gerät. Wenn die App nicht geöffnet wird, liegt das Problem in Ihrer Branch- oder AASA-Konfiguration – nicht bei Braze.
  2. Fügen Sie den Branch-Link in die Notizen-App ein und tippen Sie darauf. Universal Links funktionieren über die Notizen-App zuverlässiger als über die Adressleiste von Safari.

Allgemeine Tipps zur Fehlerbehebung

Verwenden Sie die ausführliche Protokollierung

Aktivieren Sie die ausführliche Protokollierung, um genau zu sehen, wie das SDK Links verarbeitet. Wichtige Einträge, auf die Sie achten sollten:

Protokolleintrag Bedeutung
Opening '<URL>': - channel: notification Das SDK verarbeitet einen Link aus einer Push-Benachrichtigung
Opening '<URL>': - channel: inAppMessage Das SDK verarbeitet einen Link aus einer In-App-Nachricht
Opening '<URL>': - channel: contentCard Das SDK verarbeitet einen Link aus einer Content Card
useWebView: true Das SDK öffnet die URL in der In-App-WebView
isUniversalLink: true Das SDK hat die URL als Universal Link identifiziert

Weitere Informationen zum Lesen dieser Protokolle finden Sie unter Ausführliche Protokolle lesen.

Bevor Sie über Braze testen, überprüfen Sie, ob Ihr Deeplink oder Universal Link eigenständig funktioniert:

  • Benutzerdefiniertes Schema: Führen Sie xcrun simctl openurl booted "myapp://path" im Terminal aus.
  • Universal Link: Fügen Sie die URL in die Notizen-App auf einem physischen Gerät ein und tippen Sie darauf. Testen Sie nicht über die Adressleiste von Safari, da iOS eingegebene URLs anders behandelt als angetippte Links.
  • Branch-Link: Öffnen Sie den Branch-Link über die Notizen-App auf einem Gerät.

Testen Sie auf einem physischen Gerät

Universal Links werden im iOS-Simulator nur eingeschränkt unterstützt. Testen Sie stets auf einem physischen Gerät, um genaue Ergebnisse zu erzielen. Falls Sie in einem Simulator testen müssen, fügen Sie die .entitlements-Datei zur Build-Phase Copy Bundle Resources hinzu.
New Stuff!