Vinculación en profundidad para iOS

Para obtener información introductoria sobre los vínculos profundos, consulta el artículo de nuestra Guía del usuario. Si quieres implementar vínculos en profundidad por primera vez en tu aplicación Braze, los pasos siguientes te ayudarán a empezar.

Paso 1: Registrar un esquema

Debes indicar un esquema personalizado en el archivo Info.plist. La estructura de navegación está definida por una matriz de diccionarios. Cada uno de esos diccionarios contiene una matriz de cadenas.

Utiliza Xcode para editar tu archivo Info.plist:

1. Añade una nueva clave, URL types. Xcode lo convertirá automáticamente en una matriz que contiene un diccionario llamado Item 0.
2. Dentro de Item 0, añade una clave URL identifier. Establece el valor a tu esquema personalizado.
3. Dentro de Item 0, añade una clave URL Schemes. Será automáticamente una matriz que contendrá una cadena Item 0.
4. Configura URL Schemes » Item 0 a tu esquema personalizado.

Alternativamente, si deseas editar tu archivo Info.plist directamente, puedes seguir esta especificación:

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>

Paso 2: Permitir el esquema personalizado (iOS 9+)

A partir de iOS 9, las aplicaciones deben tener una lista de esquemas personalizados que la aplicación puede abrir. Si intentas llamar a esquemas que están fuera de esta lista, el sistema registrará un error en los registros del dispositivo y el vínculo profundo no se abrirá. Un ejemplo de este error es el siguiente:

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

Por ejemplo, si un mensaje dentro de la aplicación debe abrir la aplicación de Facebook al tocarlo, la aplicación tiene que tener el esquema personalizado de Facebook (fb) en la lista de permitidos. De lo contrario, el sistema rechazará el vínculo profundo. Los vínculos profundos que dirigen a una página o vista dentro de tu propia aplicación siguen requiriendo que el esquema personalizado de tu aplicación aparezca en el Info.plist de tu aplicación.

Debes añadir todos los esquemas a los que la aplicación necesita vincularse en profundidad en una lista de permitidos en el Info.plist de tu aplicación con la clave LSApplicationQueriesSchemes. Por ejemplo:

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

Para más información, consulta la documentación de Apple sobre la clave LSApplicationQueriesSchemes.

Paso 3: Implementa un controlador

Tras activar tu aplicación, iOS llamará al método application:openURL:options:. El argumento importante es el objeto NSURL.

• objective-c
• swift

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];
  // Here you should insert code to take some action based upon the path and query.
  return YES;
}

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
  // Here you should insert code to take some action based upon the path and query.
  return true
}

Enlaces universales

Para utilizar los enlaces universales, asegúrate de haber añadido un dominio registrado a las capacidades de tu aplicación y de haber subido un archivo apple-app-site-association. A continuación, implementa el método application:continueUserActivity:restorationHandler: en tu AppDelegate. Por ejemplo:

• objective-c
• swift

1
2
3
4
5
6
7
8
9
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
  restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
  if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
    NSURL *url = userActivity.webpageURL;
    // Handle url
  }
  return YES;
}

1
2
3
4
5
6
7
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  if (userActivity.activityType == NSUserActivityTypeBrowsingWeb) {
    let url = userActivity.webpageURL
    // Handle url
  }
  return true
}

Consulta Apple para más información.

Seguridad en el transporte de aplicaciones (ATS)

iOS 9 introdujo un cambio importante que afecta a las URL web incrustadas en los mensajes dentro de la aplicación y en las notificaciones push.

Requisitos ATS

De la documentación de Apple: “App Transport Security es una característica que mejora la seguridad de las conexiones entre una aplicación y los servicios web. La característica consiste en requisitos de conexión predeterminados que se ajustan a las mejores prácticas para conexiones seguras. Las aplicaciones pueden anular este comportamiento predeterminado y desactivar la seguridad del transporte”.

ATS se aplica de forma predeterminada en iOS 9+. Requiere que todas las conexiones utilicen HTTPS y estén cifradas mediante TLS 1.2 con confidencialidad directa. Consulta los Requisitos para conectarse mediante ATS para obtener más información. Todas las imágenes servidas por Braze a dispositivos finales son gestionadas por una red de entrega de contenidos (“CDN”) que admite TLS 1.2 y es compatible con ATS.

A menos que se especifiquen como excepciones en el Info.plist de tu aplicación, las conexiones que no sigan estos requisitos fallarán con errores parecidos a estos:

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."

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

El cumplimiento de ATS se aplica a los enlaces abiertos dentro de la aplicación móvil (nuestro tratamiento predeterminado de los enlaces en los que se hace clic) y no se aplica a los sitios abiertos externamente a través de un navegador web.

Gestión de los requisitos ATS

Puedes manejar ATS de una de las tres formas siguientes:

Confirma que todos los enlaces cumplen con ATS (recomendado)

Tu integración con Braze puede cumplir los requisitos de ATS garantizando que cualquier enlace existente al que dirijas a los usuarios (a través de mensajes dentro de la aplicación y campañas push) cumpla los requisitos de ATS. Aunque hay formas de eludir las restricciones de ATS, te recomendamos que compruebes que todas las URL enlazadas cumplen con ATS. Dado el creciente énfasis de Apple en la seguridad de las aplicaciones, no está garantizado que Apple admita los siguientes enfoques para permitir excepciones ATS.

Una herramienta SSL puede ayudarte a detectar problemas de seguridad del servidor web. Esta prueba de servidor SSL de Qualys, Inc. proporciona una línea específica para el cumplimiento de Apple ATS 9 e iOS 9.

Desactiva parcialmente ATS

Puedes permitir que un subconjunto de enlaces con determinados dominios o esquemas sean tratados como excepciones a las reglas de ATS. Tu integración con Braze satisfará los requisitos de ATS si cada enlace que utilices en un canal de mensajería de Braze es compatible con ATS o se gestiona mediante una excepción.

Para añadir un dominio como excepción de ATS, añade lo siguiente al archivo Info.plist de tu aplicación:

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>

Consulta el artículo de Apple sobre las claves de seguridad para el transporte de aplicaciones para obtener más información.

Desactiva ATS por completo

Puedes desactivar ATS por completo. Ten en cuenta que no es una práctica recomendada, tanto por la pérdida de protecciones de seguridad como por la futura compatibilidad con iOS. Para desactivar ATS, inserta lo siguiente en el archivo Info.plist de tu aplicación:

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

Consulta Enviar una aplicación con seguridad de transporte de aplicaciones para obtener más información sobre cómo depurar fallos de ATS.

Codificación de URL

A partir del SDK v2.21.0 de Braze para iOS, el SDK codifica porcentualmente los enlaces para crear NSURL válidos. Todos los caracteres de enlace que no estén permitidos en una URL correctamente formada, como los caracteres Unicode, se escaparán porcentualmente.

Para decodificar un enlace codificado, utiliza el método NSString stringByRemovingPercentEncoding. Ten en cuenta que también debes devolver YES en ABKURLDelegate y que es necesaria una llamada a la acción para desencadenar la gestión de la URL por parte de la aplicación. Por ejemplo:

• objective-c
• swift

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

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
  }

Personalización

Personalización predeterminada de WebView

La clase personalizable ABKModalWebViewController muestra las URL web abiertas por el SDK, normalmente cuando se selecciona “Abrir URL web dentro de la aplicación” para un vínculo profundo web.

Puedes declarar una categoría para la clase ABKModalWebViewController, o modificarla directamente, para aplicar la personalización a la vista web. Consulta el archivo .h y el archivo .m de la clase para obtener más detalles.

Personalización de la gestión de enlaces

El protocolo ABKURLDelegate puede utilizarse para personalizar la gestión de las URL, como los vínculos profundos, las URL web y los enlaces universales. Para configurar el delegado durante la inicialización de Braze, pasa un objeto delegado a ABKURLDelegateKey en appboyOptions de startWithApiKey:inApplication:withAppboyOptions:. A continuación, Braze llamará a la implementación de handleAppboyURL:fromChannel:withExtras: de tu delegado antes de gestionar cualquier URI.

Ejemplo de integración: ABKURLDelegate

• objective-c
• swift

1
2
3
4
5
6
7
8
- (BOOL)handleAppboyURL:(NSURL *)url fromChannel:(ABKChannel)channel withExtras:(NSDictionary *)extras {
  if ([[url.host lowercaseString] isEqualToString:@"MY-DOMAIN.com"]) {
    // Custom handle link here
    return YES;
  }
  // Let Braze handle links otherwise
  return NO;
}

1
2
3
4
5
6
7
8
func handleAppboyURL(_ url: URL?, from channel: ABKChannel, withExtras extras: [AnyHashable : Any]?) -> Bool {
  if (url.host == "MY-DOMAIN.com") {
    // Custom handle link here
    return true;
  }
  // Let Braze handle links otherwise
  return false;
}

Para más información, consulta ABKURLDelegate.h.

Casos de uso frecuentes

Vinculación en profundidad con la configuración de la aplicación

iOS puede llevar a los usuarios de tu aplicación a su página en la aplicación de configuración de iOS. Puedes aprovechar UIApplicationOpenSettingsURLString para crear un vínculo profundo a la configuración desde notificaciones push y mensajes dentro de la aplicación.

1. En primer lugar, asegúrate de que tu aplicación está configurada para vínculos profundos basados en esquemas o enlaces universales.
2. Decide un URI para la vinculación en profundidad a la página de configuración (por ejemplo, myapp://settings o https://www.braze.com/settings).
3. Si utilizas vínculos profundos personalizados basados en esquemas, añade el siguiente código a tu método application:openURL:options::

• objective-c
• swift

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

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:UIApplicationOpenSettingsURLString)!)
  }
  return true
}