Deep linking para iOS

Para obter informações introdutórias sobre deep links, consulte nosso artigo do Guia do Usuário. Se você está procurando implementar deep links pela primeira vez no seu app da Braze, as etapas abaixo te ajudarão a começar.

Etapa 1: Registrar um esquema

Você deve declarar um esquema personalizado no arquivo Info.plist. A estrutura de navegação é definida por um array de dicionários. Cada um desses dicionários contém um array de strings.

Use o Xcode para editar seu arquivo Info.plist:

1. Adicione uma nova chave, URL types. O Xcode fará automaticamente disso um array contendo um dicionário chamado Item 0.
2. Dentro de Item 0, adicione uma chave URL identifier. Defina o valor para seu esquema personalizado.
3. Dentro de Item 0, adicione uma chave URL Schemes. Isso será automaticamente um array contendo uma string Item 0.
4. Defina URL Schemes » Item 0 para seu esquema personalizado.

Alternativamente, se você deseja editar seu arquivo Info.plist diretamente, siga esta especificação:

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>

Etapa 2: Adicionar o esquema personalizado à lista de permissões (iOS 9+)

A partir do iOS 9, os apps devem ter uma lista de permissões de esquemas personalizados que o app tem permissão para abrir. Tentar chamar esquemas fora desta lista fará com que o sistema registre um erro nos logs do dispositivo, e o deep link não abrirá. Um exemplo desse erro se parece com isto:

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

Por exemplo, se uma mensagem no app deve abrir o app do Facebook quando tocada, o app precisa ter o esquema personalizado do Facebook (fb) na lista de permissões. Caso contrário, o sistema rejeitará o deep link. Deep links que direcionam para uma página ou visualização dentro do seu próprio app ainda exigem que o esquema personalizado do seu app esteja listado no Info.plist do seu app.

Você deve adicionar todos os esquemas que o app precisa para fazer deep linking em uma lista de permissões no Info.plist do seu app com a chave LSApplicationQueriesSchemes. Por exemplo:

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

Para saber mais, consulte a documentação da Apple sobre a chave LSApplicationQueriesSchemes.

Etapa 3: Implementar um handler

Depois de ativar seu app, o iOS chamará o método application:openURL:options:. O argumento importante é o 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
}

Links universais

Para usar links universais, certifique-se de que você adicionou um domínio registrado às capacidades do seu app e fez upload de um arquivo apple-app-site-association. Em seguida, implemente o método application:continueUserActivity:restorationHandler: no seu AppDelegate. Por exemplo:

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

Para saber mais, consulte a Apple.

App Transport Security (ATS)

O iOS 9 introduziu uma mudança significativa que afeta URLs da web incorporadas em mensagens no app e notificações por push.

Requisitos do ATS

Da documentação da Apple: “O App Transport Security é um recurso que melhora a segurança das conexões entre um app e os serviços da web. O recurso consiste em requisitos de conexão padrão que estão em conformidade com as melhores práticas para conexões seguras. Os apps podem substituir esse comportamento padrão e desativar a segurança de transporte.”

O ATS é aplicado por padrão no iOS 9+. Ele requer que todas as conexões usem HTTPS e sejam criptografadas usando TLS 1.2 com forward secrecy. Consulte Requisitos para Conexão Usando ATS para saber mais. Todas as imagens servidas pela Braze para dispositivos finais são gerenciadas por uma rede de entrega de conteúdo (“CDN”) que suporta TLS 1.2 e é compatível com ATS.

A menos que sejam especificadas como exceções no Info.plist do seu aplicativo, as conexões que não seguirem esses requisitos falharão com erros parecidos com isto:

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)

A conformidade com ATS é aplicada para links abertos dentro do app móvel (nosso tratamento padrão de links clicados) e não se aplica a sites abertos externamente por meio de um navegador da web.

Atendendo aos requisitos do ATS

Você pode lidar com o ATS de uma das três maneiras a seguir:

Confirme se todos os links estão em conformidade com o ATS (recomendado)

Sua integração com a Braze pode atender aos requisitos do ATS garantindo que quaisquer links existentes que você direcione os usuários (através de mensagens no app e campanhas de push) atendam aos requisitos do ATS. Embora existam maneiras de contornar as restrições do ATS, recomendamos verificar se todos os URLs vinculados estão em conformidade com o ATS. Dada a ênfase crescente da Apple na segurança de aplicativos, as seguintes abordagens para permitir exceções do ATS não têm garantia de suporte pela Apple.

Uma ferramenta SSL pode ajudar a identificar problemas de segurança do servidor web. Este teste de servidor SSL da Qualys, Inc. fornece um item de linha especificamente para a conformidade com o Apple ATS 9 e o iOS 9.

Desativar parcialmente o ATS

Você pode permitir que um subconjunto de links com determinados domínios ou esquemas sejam tratados como exceções às regras do ATS. Sua integração com a Braze atenderá aos requisitos do ATS se cada link que você usar em um canal de envio de mensagens da Braze for compatível com o ATS ou tratado por uma exceção.

Para adicionar um domínio como exceção do ATS, adicione o seguinte ao arquivo Info.plist do seu app:

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>

Consulte o artigo da Apple sobre chaves de App Transport Security para saber mais.

Desativar totalmente o ATS

Você pode desativar o ATS completamente. Note que isso não é uma prática recomendada, devido tanto à perda de proteções de segurança quanto à compatibilidade futura com o iOS. Para desativar o ATS, insira o seguinte no arquivo Info.plist do seu app:

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

Consulte Shipping an App With App Transport Security para mais informações sobre como depurar falhas de ATS.

Codificação de URL

A partir do SDK da Braze para iOS v2.21.0, o SDK codifica percentualmente os links para criar NSURLs válidos. Todos os caracteres de link que não são permitidos em um URL devidamente formado, como caracteres Unicode, serão escapados por porcentagem.

Para decodificar um link codificado, use o método NSString stringByRemovingPercentEncoding. Note que você também precisa retornar YES no ABKURLDelegate e que uma chamada para ação é necessária para disparar o tratamento do URL pelo app. Por exemplo:

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

Personalização

Personalização padrão do WebView

A classe personalizável ABKModalWebViewController exibe URLs da web abertas pelo SDK, normalmente quando “Abrir URL da Web Dentro do App” é selecionado para um deep link da web.

Você pode declarar uma categoria para, ou modificar diretamente, a classe ABKModalWebViewController para aplicar a personalização à visualização da web. Verifique o arquivo .h e o arquivo .m da classe para mais detalhes.

Personalização do tratamento de links

O protocolo ABKURLDelegate pode ser usado para personalizar o tratamento de URLs, como deep links, URLs da web e links universais. Para definir o delegado durante a inicialização da Braze, passe um objeto delegado para o ABKURLDelegateKey no appboyOptions de startWithApiKey:inApplication:withAppboyOptions:. A Braze chamará a implementação do seu delegado de handleAppboyURL:fromChannel:withExtras: antes de tratar qualquer URI.

Exemplo de integração: 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 saber mais, consulte ABKURLDelegate.h.

Casos de uso frequentes

Deep linking para as configurações do app

O iOS pode levar os usuários do seu app para a sua página no aplicativo de configurações do iOS. Você pode aproveitar UIApplicationOpenSettingsURLString para fazer deep link de usuários para as configurações a partir de notificações por push e mensagens no app.

1. Primeiro, confira se o seu aplicativo está configurado para deep links baseados em esquema ou links universais.
2. Decida um URI para deep linking para a página de Configurações (por exemplo, myapp://settings ou https://www.braze.com/settings).
3. Se você estiver usando deep links baseados em esquemas personalizados, adicione o seguinte código ao seu 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
}