Création de liens profonds dans les messages in-app

Conditions préalables

Avant de pouvoir utiliser cette fonctionnalité, vous devrez intégrer le SDK Swift Braze.

Conseil

Pour obtenir de l’aide afin de choisir entre les liens profonds à schéma personnalisé, les liens universels et « Ouvrir l’URL Web dans l’application », consultez le guide de création de liens profonds iOS. Pour la résolution des problèmes, consultez Résolution des problèmes de création de liens profonds.

Gestion des liens profonds

Étape 1 : Enregistrer un schéma

Pour gérer les liens profonds, un schéma personnalisé doit être déclaré dans votre fichier Info.plist. La structure de navigation est définie par un tableau de dictionnaires. Chacun de ces dictionnaires contient un tableau de chaînes de caractères.

Utilisez Xcode pour modifier votre fichier Info.plist :

1. Ajoutez une nouvelle clé, URL types. Xcode en fera automatiquement un tableau contenant un dictionnaire appelé Item 0.
2. Dans Item 0, ajoutez une clé URL identifier. Définissez la valeur sur votre schéma personnalisé.
3. Dans Item 0, ajoutez une clé URL Schemes. Ce sera automatiquement un tableau contenant une chaîne Item 0.
4. Définissez URL Schemes » Item 0 sur votre schéma personnalisé.

Sinon, si vous souhaitez modifier votre fichier Info.plist directement, vous pouvez suivre cette spécification :

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>

Étape 2 : Ajouter une liste d’autorisations de schémas

Vous devez déclarer les schémas d’URL que vous souhaitez transmettre à canOpenURL(_:) en ajoutant la clé LSApplicationQueriesSchemes au fichier Info.plist de votre application. Toute tentative d’appel de schémas en dehors de cette liste d’autorisations entraînera l’enregistrement d’une erreur dans les journaux de l’appareil, et le lien profond ne s’ouvrira pas. Un exemple de cette erreur ressemblera à ceci :

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

Par exemple, si un message in-app doit ouvrir l’application Facebook lorsqu’on appuie dessus, l’application doit avoir le schéma personnalisé de Facebook (fb) dans votre liste d’autorisations. Sinon, le système rejettera le lien profond. Les liens profonds qui dirigent vers une page ou une vue au sein de votre propre application nécessitent toujours que le schéma personnalisé de votre application soit répertorié dans le fichier Info.plist de votre application.

Votre liste d’autorisations pourrait ressembler à ceci :

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

Pour plus d’informations, reportez-vous à la documentation d’Apple sur la clé LSApplicationQueriesSchemes.

Étape 3 : Implémenter un gestionnaire

Après l’activation de votre application, iOS appellera la méthode application:openURL:options:. L’argument important est l’objet NSURL.

• 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 Security (ATS)

Selon la définition d’Apple, « App Transport Security est une fonctionnalité qui améliore la sécurité des connexions entre une application et les services web. La fonctionnalité consiste en des exigences de connexion par défaut conformes aux meilleures pratiques visant les connexions sécurisées. Les applications peuvent remplacer ce comportement par défaut et désactiver la sécurité du transport. »

L’ATS est appliqué par défaut. Il nécessite que toutes les connexions utilisent HTTPS et soient chiffrées à l’aide de TLS 1.2 avec confidentialité de transmission. Pour plus d’informations, reportez-vous à la section Exigences pour la connexion à l’aide de l’ATS. Toutes les images servies par Braze aux terminaux sont gérées par un réseau de diffusion de contenu (« CDN ») qui prend en charge TLS 1.2 et est compatible avec ATS.

À moins qu’elles ne soient spécifiées comme exceptions dans le fichier Info.plist de votre application, les connexions qui ne respectent pas ces exigences échoueront et généreront des erreurs similaires à celles ci-dessous.

Exemple d’erreur 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."

Exemple d’erreur 2 :

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

La conformité ATS est appliquée aux liens ouverts dans l’application mobile (notre gestion par défaut des liens cliqués) et ne s’applique pas aux sites ouverts à l’extérieur via un navigateur web.

Utilisation de l’ATS

Vous pouvez gérer l’ATS de l’une des manières suivantes, mais nous vous recommandons de vous conformer aux exigences de l’ATS.

• se conformer
• désactiver partiellement
• désactiver complètement

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>

Décodage des URL

Le SDK encode les liens en pourcentage pour créer des URL valides. Tous les caractères de lien qui ne sont pas autorisés dans une URL correctement formée, tels que les caractères Unicode, seront échappés en pourcentage.

Pour décoder un lien encodé, utilisez la propriété String removingPercentEncoding. Vous devez également renvoyer true dans BrazeDelegate.braze(_:shouldOpenURL:). Un appel à l’action est nécessaire pour déclencher le traitement de l’URL par votre application. Par exemple :

• 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;
}

Création de liens profonds vers les paramètres de l’application

Vous pouvez utiliser UIApplicationOpenSettingsURLString pour créer des liens profonds redirigeant les utilisateurs vers les paramètres de votre application à partir des notifications push Braze et des messages in-app.

Pour diriger les utilisateurs de votre application vers les paramètres iOS :

1. Tout d’abord, assurez-vous que votre application est configurée pour les liens profonds basés sur un schéma ou les liens universels.
2. Choisissez un URI pour le lien profond vers la page Paramètres (par exemple, myapp://settings ou https://www.braze.com/settings).
3. Si vous utilisez des liens profonds basés sur un schéma personnalisé, ajoutez le code suivant à votre méthode application:openURL:options: :

• 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;
}

Options de personnalisation

Personnalisation de la WebView par défaut

La classe Braze.WebViewController affiche les URL web ouvertes par le SDK, généralement lorsque l’option « Ouvrir l’URL Web dans l’application » est sélectionnée pour un lien profond web.

Vous pouvez personnaliser le Braze.WebViewController via la méthode de délégué BrazeDelegate.braze(_:willPresentModalWithContext:).

Personnalisation de la gestion des liens

Le protocole BrazeDelegate peut être utilisé pour personnaliser la gestion des URL telles que les liens profonds, les URL web et les liens universels. Pour définir le délégué lors de l’initialisation de Braze, définissez un objet délégué sur l’instance Braze. Braze appellera ensuite l’implémentation de shouldOpenURL de votre délégué avant de gérer les URI.

Lorsqu’une notification push ou un message in-app utilise Ouvrir l’URL web dans l’application mobile, Braze transmet context.useWebView == true sur Braze.URLContext. Lorsque le message ouvre l’URL dans le navigateur système, useWebView est false. Inspectez context.useWebView dans braze(_:shouldOpenURL:) pour adapter votre gestion personnalisée — par exemple, pour ouvrir un WebViewController in-app uniquement lorsque la campagne a demandé un affichage in-app.

Liens universels

Braze prend en charge les liens universels dans les notifications push, les messages in-app et les Content Cards. Pour activer la prise en charge des liens universels, configuration.forwardUniversalLinks doit être défini sur true.

Lorsque cette option est activée, Braze transmet les liens universels à l’AppDelegate de votre application via la méthode application:continueUserActivity:restorationHandler:.

Votre application doit également être configurée pour gérer les liens universels. Reportez-vous à la documentation d’Apple pour vous assurer que votre application est configurée correctement pour les liens universels.

Avertissement

Le transfert de liens universels nécessite l’accès aux droits de l’application. Lorsque l’application est exécutée dans un simulateur, ces droits ne sont pas directement disponibles et les liens universels ne sont pas transmis aux gestionnaires du système. Pour ajouter la prise en charge aux builds de simulateur, vous pouvez ajouter le fichier .entitlements de l’application à la phase de build Copy Bundle Resources. Consultez la documentation de forwardUniversalLinks pour plus de détails.

Remarque

Le SDK n’interroge pas le fichier apple-app-site-association de vos domaines. Il fait la différence entre les liens universels et les URL ordinaires en ne tenant compte que du nom de domaine. Par conséquent, le SDK ne respecte aucune règle d’exclusion définie dans le fichier apple-app-site-association conformément à la documentation Prise en charge des domaines associés.

Exemples

BrazeDelegate

Voici un exemple utilisant BrazeDelegate. Pour plus d’informations, consultez la référence du SDK Swift de Braze.

• 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;
}