Deeplinking in In-App-Nachrichten

Voraussetzungen

Bevor Sie dieses Feature nutzen können, müssen Sie das Swift Braze SDK integrieren.

Tipp

Für Unterstützung bei der Auswahl zwischen benutzerdefinierten Deeplinks, Universal-Links und „Open Web URL Inside App“ lesen Sie den iOS-Deeplinking-Leitfaden. Informationen zur Fehlerbehebung finden Sie unter Fehlerbehebung bei Deeplinking.

Handhabung von Deeplinks

1. Schritt: Ein Schema registrieren

Um Deeplinks setzen zu können, muss ein angepasstes Schema in Ihrer Info.plist-Datei angegeben sein. Die Navigationsstruktur wird durch ein Array von Wörterbüchern definiert. Jedes dieser Wörterbücher enthält ein String-Array.

Verwenden Sie Xcode, um Ihre Info.plist-Datei zu bearbeiten:

1. Fügen Sie einen neuen Schlüssel hinzu, URL types. Xcode macht daraus automatisch ein Array, das ein Wörterbuch namens Item 0 enthält.
2. Fügen Sie innerhalb von Item 0 einen Schlüssel URL identifier hinzu. Stellen Sie den Wert auf Ihr angepasstes Schema ein.
3. Fügen Sie innerhalb von Item 0 einen Schlüssel URL Schemes hinzu. Dies wird automatisch ein Array sein, das einen Item 0-String enthält.
4. Stellen Sie URL Schemes » Item 0 auf Ihr angepasstes Schema ein.

Wenn Sie Ihre Info.plist-Datei direkt bearbeiten möchten, können Sie auch dieser Spezifikation folgen:

1
2
3
4
5
6
7
8
9
10
11
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>YOUR.SCHEME</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR.SCHEME</string>
        </array>
    </dict>
</array>

2. Schritt: Eine Schema-Allowlist hinzufügen

Sie müssen die URL-Schemata, die Sie an canOpenURL(_:) übergeben möchten, deklarieren, indem Sie den Schlüssel LSApplicationQueriesSchemes in die Datei Info.plist Ihrer App einfügen. Der Versuch, Schemata außerhalb dieser Allowlist aufzurufen, führt dazu, dass das System einen Fehler in den Protokollen des Geräts aufzeichnet und der Deeplink nicht geöffnet wird. Ein Beispiel für diesen Fehler sieht wie folgt aus:

1
<Warning>: -canOpenURL: failed for URL: "yourapp://deeplink" – error: "This app is not allowed to query for scheme yourapp"

Wenn zum Beispiel eine In-App-Nachricht beim Antippen die Facebook-App öffnen soll, muss die App das angepasste Schema von Facebook (fb) in Ihrer Allowlist haben. Andernfalls wird das System den Deeplink ablehnen. Deeplinks, die auf eine Seite oder Ansicht innerhalb Ihrer eigenen App verweisen, erfordern nach wie vor, dass das angepasste Schema Ihrer App in der Info.plist Ihrer App aufgeführt ist.

Ihre Beispiel-Allowlist könnte etwa so aussehen:

1
2
3
4
5
6
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>myapp</string>
    <string>fb</string>
    <string>twitter</string>
</array>

Weitere Informationen finden Sie in der Dokumentation von Apple zum Schlüssel LSApplicationQueriesSchemes.

3. Schritt: Einen Handler implementieren

Nachdem Ihre App aktiviert wurde, ruft iOS die Methode application:openURL:options: auf. Das wichtige Argument ist das NSURL-Objekt.

• swift
• objective-c

1
2
3
4
5
6
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
  let path = url.path
  let query = url.query
  // Insert your code here to take some action based upon the path and query.
  return true
}

1
2
3
4
5
6
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
  NSString *path  = [url path];
  NSString *query = [url query];
  // Insert your code here to take some action based upon the path and query.
  return YES;
}

App-Transport-Sicherheit (ATS)

Laut Apple ist „App Transport Security ein Feature, das die Sicherheit der Verbindungen zwischen einer App und Webdiensten verbessert. Das Feature besteht aus Standard-Verbindungsanforderungen, die den Best Practices für sichere Verbindungen entsprechen. Apps können dieses Standardverhalten außer Kraft setzen und die Transportsicherheit deaktivieren.“

ATS wird standardmäßig angewendet. Es erfordert, dass alle Verbindungen HTTPS verwenden und mit TLS 1.2 mit Forward Secrecy verschlüsselt werden. Weitere Informationen finden Sie unter Voraussetzungen für die Verbindung mit ATS. Alle Bilder, die von Braze an Endgeräte geliefert werden, werden von einem Content Delivery Network („CDN“) verarbeitet, das TLS 1.2 unterstützt und mit ATS kompatibel ist.

Sofern sie nicht als Ausnahmen in der Info.plist Ihrer Anwendung angegeben sind, schlagen Verbindungen, die diese Anforderungen nicht erfüllen, mit Fehlern fehl, die den folgenden ähneln.

Beispielfehler 1:

1
2
CFNetwork SSLHandshake failed (-9801)
Error Domain=NSURLErrorDomain Code=-1200 "An SSL error has occurred, and a secure connection to the server cannot be made."

Beispielfehler 2:

1
NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9802)

Die ATS-Konformität wird für Links durchgesetzt, die innerhalb der mobilen App geöffnet werden (unsere Standardbehandlung von angeklickten Links), und gilt nicht für Websites, die extern über einen Webbrowser geöffnet werden.

Arbeiten mit ATS

Sie können ATS auf eine der folgenden Arten handhaben, aber wir empfehlen, die ATS-Anforderungen zu erfüllen.

• einhalten
• teilweise deaktivieren
• vollständig deaktivieren

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    <key>NSExceptionDomains</key>
    <dict>
        <key>example.com</key>
        <dict>
            <key>NSExceptionAllowsInsecureHTTPLoads</key>
            <false/>
            <key>NSIncludesSubdomains</key>
            <true/>
        </dict>
    </dict>
</dict>

1
2
3
4
5
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

URLs dekodieren

Das SDK kodiert Links prozentual, um gültige URLs zu erstellen. Alle Link-Zeichen, die in einer korrekt geformten URL nicht zulässig sind, wie z. B. Unicode-Zeichen, werden prozentual escaped.

Um einen kodierten Link zu dekodieren, verwenden Sie die String-Eigenschaft removingPercentEncoding. Sie müssen außerdem true in BrazeDelegate.braze(_:shouldOpenURL:) zurückgeben. Ein Call-to-Action ist erforderlich, um die Verarbeitung der URL durch Ihre App zu triggern. Zum Beispiel:

• swift
• objective-c

1
2
3
4
5
  func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let urlString = url.absoluteString.removingPercentEncoding
    // Handle urlString
    return true
  }

1
2
3
4
5
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)options {
  NSString *urlString = [url.absoluteString stringByRemovingPercentEncoding];
  // Handle urlString
  return YES;
}

Deeplinking zu App-Einstellungen

Sie können UIApplicationOpenSettingsURLString nutzen, um Nutzer:innen über Push-Benachrichtigungen und In-App-Nachrichten von Braze einen Deeplink zu den Einstellungen Ihrer App zu setzen.

Um Nutzer:innen aus Ihrer App in die iOS-Einstellungen zu bringen:

1. Vergewissern Sie sich zunächst, dass Ihre Anwendung entweder für schemabasierte Deeplinks oder für universelle Links eingerichtet ist.
2. Legen Sie eine URI für Deeplinks auf die Seite Einstellungen fest (z. B. myapp://settings oder https://www.braze.com/settings).
3. Wenn Sie angepasste schemabasierte Deeplinks verwenden, fügen Sie den folgenden Code zu Ihrer application:openURL:options:-Methode hinzu:

• swift
• objective-c

1
2
3
4
5
6
7
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
  let path = url.path
  if (path == "settings") {
    UIApplication.shared.openURL(URL(string:UIApplication.openSettingsURLString)!)
  }
  return true
}

1
2
3
4
5
6
7
8
9
10
- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  NSString *path  = [url path];
  if ([path isEqualToString:@"settings"]) {
    NSURL *settingsURL = [NSURL URLWithString:UIApplicationOpenSettingsURLString];
    [[UIApplication sharedApplication] openURL:settingsURL];
  }
  return YES;
}

Anpassungsoptionen

Standard-WebView-Anpassung

Die Klasse Braze.WebViewController zeigt vom SDK geöffnete Web-URLs an, typischerweise wenn für einen Web-Deeplink „Open Web URL Inside App“ ausgewählt wurde.

Sie können den Braze.WebViewController über die Delegate-Methode BrazeDelegate.braze(_:willPresentModalWithContext:) anpassen.

Anpassung der Link-Handhabung

Das Protokoll BrazeDelegate kann verwendet werden, um die Handhabung von URLs wie Deeplinks, Web-URLs und universellen Links anzupassen. Um den Delegaten während der Initialisierung von Braze zu setzen, setzen Sie ein Delegate-Objekt auf die Braze-Instanz. Braze ruft dann die Implementierung von shouldOpenURL in Ihrem Delegaten auf, bevor es URIs verarbeitet.

Wenn eine Push-Benachrichtigung oder In-App-Nachricht Web-URL in der mobilen App öffnen verwendet, übergibt Braze context.useWebView == true an Braze.URLContext. Wenn die Nachricht die URL stattdessen im Systembrowser öffnet, ist useWebView false. Prüfen Sie context.useWebView in braze(_:shouldOpenURL:), um Ihre benutzerdefinierte Handhabung zu verzweigen – zum Beispiel, um einen In-App-WebViewController nur dann zu öffnen, wenn die Campaign die In-App-Anzeige angefordert hat.

Universelle Links

Braze unterstützt universelle Links in Push-Benachrichtigungen, In-App-Nachrichten und Content Cards. Um die Unterstützung für universelle Links zu aktivieren, muss configuration.forwardUniversalLinks auf true gesetzt sein.

Wenn diese Funktion aktiviert ist, leitet Braze universelle Links über die Methode application:continueUserActivity:restorationHandler: an den AppDelegate Ihrer App weiter.

Ihre Anwendung muss ebenfalls für den Umgang mit universellen Links eingerichtet sein. Lesen Sie die Dokumentation von Apple, um sicherzustellen, dass Ihre Anwendung korrekt für universelle Links konfiguriert ist.

Warnung

Die Weiterleitung universeller Links erfordert den Zugriff auf die Anwendungsberechtigungen. Wenn Sie die Anwendung in einem Simulator ausführen, sind diese Berechtigungen nicht direkt verfügbar und universelle Links werden nicht an die System-Handler weitergeleitet. Um die Unterstützung für Simulator-Builds hinzuzufügen, können Sie die .entitlements-Datei der Anwendung in der Build-Phase Copy Bundle Resources hinzufügen. Weitere Details finden Sie in der Dokumentation zu forwardUniversalLinks.

Hinweis

Das SDK fragt die apple-app-site-association-Datei Ihrer Domains nicht ab. Es unterscheidet zwischen universellen Links und regulären URLs, indem es nur den Domain-Namen betrachtet. Infolgedessen beachtet das SDK keine Ausschlussregel, die in der apple-app-site-association gemäß Unterstützung zugehöriger Domains definiert ist.

Beispiele

BrazeDelegate

Hier ist ein Beispiel mit BrazeDelegate. Weitere Informationen finden Sie in der Braze Swift SDK-Referenz.

• swift
• objective-c

1
2
3
4
5
6
7
8
func braze(_ braze: Braze, shouldOpenURL context: Braze.URLContext) -> Bool {
  if context.url.host == "MY-DOMAIN.com" {
    // Custom handle link here
    return false
  }
  // Let Braze handle links otherwise
  return true
}

1
2
3
4
5
6
7
8
- (BOOL)braze:(Braze *)braze shouldOpenURL:(BRZURLContext *)context {
  if ([[context.url.host lowercaseString] isEqualToString:@"MY-DOMAIN.com"]) {
    // Custom handle link here
    return NO;
  }
  // Let Braze handle links otherwise
  return YES;
}