Guia de integração

André Cipriani Bandarra

Observação: um guia de início rápido mais simples para Atividades confiáveis na Web já está disponível.

A configuração de uma atividade da Web confiável não exige que os desenvolvedores criem código Java, mas o Android Studio é necessário. Este guia foi criado usando o Android Studio 3.3. Consulte a documentação sobre como instalar.

Criar um projeto de Atividade Confiável na Web

Ao usar atividades confiáveis da Web, o projeto precisa ser direcionado à API 16 ou mais recente.

Observação: esta seção vai orientar você sobre como configurar um novo projeto no Android Studio. Se você já conhece a ferramenta, pule para a seção Como usar a biblioteca de atividades na Web confiável.

Abra o Android Studio e clique em Start a new Android Studio project.

O Android Studio vai solicitar que você escolha um tipo de atividade. Como as atividades da Web confiáveis usam uma atividade fornecida pela biblioteca de suporte, escolha Add No Activity e clique em Next.

Na próxima etapa, o assistente vai solicitar configurações para o projeto. Confira uma breve descrição de cada campo:

• Name:o nome que será usado para seu aplicativo no Início do Android.
• Nome do pacote:um identificador exclusivo para apps Android na Play Store e em dispositivos Android. Consulte a documentação para mais informações sobre os requisitos e as práticas recomendadas para criar nomes de pacote para apps Android.
• Salvar localização:onde o Android Studio vai criar o projeto no sistema de arquivos.
• Language:o projeto não exige a escrita de código Java ou Kotlin. Selecione Java como padrão.
• Nível mínimo da API:a Biblioteca de suporte exige pelo menos a API de nível 16. Selecione a API 16 ou qualquer versão acima.

Deixe as outras caixas de seleção desmarcadas, já que não vamos usar apps instantâneos ou artefatos do AndroidX, e clique em Concluir.

Acessar a Biblioteca de Suporte de Atividades Confiáveis na Web

Para configurar a biblioteca Trusted Web Activity no projeto, é necessário editar o arquivo de build do aplicativo. Procure a seção Gradle Scripts no Project Navigator. Há dois arquivos chamados build.gradle, o que pode ser um pouco confuso, e as descrições entre parênteses ajudam a identificar o correto.

O arquivo que estamos procurando é aquele com o módulo Module ao lado do nome.

A biblioteca Trusted Web Activities usa recursos do Java 8, e a primeira mudança ativa o Java 8. Adicione uma seção compileOptions à parte de baixo da seção android, conforme abaixo:

android {
        ...
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
    }
}

A próxima etapa vai adicionar a Biblioteca de Suporte a Atividade da Web Confiável ao projeto. Adicione uma nova dependência à seção dependencies:

dependencies {
    implementation 'com.google.androidbrowserhelper:androidbrowserhelper:2.2.0'
}

O Android Studio vai mostrar uma solicitação para sincronizar o projeto mais uma vez. Clique no link Sync Now e sincronize.

Iniciar a atividade confiável na Web

Para configurar a atividade da Web confiável, edite o manifesto do app Android.

No Project Navigator, expanda a seção app, seguida pelos manifests e clique duas vezes em AndroidManifest.xml para abrir o arquivo.

Como pedimos ao Android Studio para não adicionar nenhuma atividade ao nosso projeto ao criá-lo, o manifesto está vazio e contém apenas a tag do aplicativo.

Adicione a atividade da Web confiável inserindo uma tag activity na tag application:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.example.twa.myapplication">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme"
        tools:ignore="GoogleAppIndexingWarning">
        <activity
            android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">

           <!-- Edit android:value to change the url opened by the Trusted Web Activity -->
           <meta-data
               android:name="android.support.customtabs.trusted.DEFAULT_URL"
               android:value="https://airhorner.com" />

           <!-- This intent-filter adds the Trusted Web Activity to the Android Launcher -->
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>

           <!--
             This intent-filter allows the Trusted Web Activity to handle Intents to open
             airhorner.com.
           -->
           <intent-filter>
               <action android:name="android.intent.action.VIEW"/>
               <category android:name="android.intent.category.DEFAULT" />
               <category android:name="android.intent.category.BROWSABLE"/>

               <!-- Edit android:host to handle links to the target URL-->
               <data
                 android:scheme="https"
                 android:host="airhorner.com"/>
           </intent-filter>
        </activity>
    </application>
</manifest>

As tags adicionadas ao XML são o manifesto do app Android padrão. Há duas informações relevantes para o contexto das Atividades confiáveis na Web:

1. A tag meta-data informa à atividade confiável na Web qual URL ela deve abrir. Mude o atributo android:value pelo URL do PWA que você quer abrir. Neste exemplo, é https://airhorner.com.
2. A segunda tag intent-filter permite que a atividade confiável na Web intercepte intents do Android que abrem https://airhorner.com. O atributo android:host dentro da tag data precisa apontar para o domínio que está sendo aberto pela atividade confiável na Web.

Observação: ao executar o projeto nessa fase, a barra de URL das guias personalizadas ainda vai aparecer na parte de cima da tela. Isso não é um bug.

A próxima seção vai mostrar como configurar Digital AssetLinks para verificar a relação entre o site e o app e remover a barra de URL.

Remover a barra de URL

As atividades confiáveis da Web exigem uma associação entre o aplicativo Android e o site para remover a barra de URL.

Essa associação é criada por meio de Links de recursos digitais e precisa ser estabelecida nas duas vias, vinculando o app ao site e o site ao app.

É possível configurar o app para a validação do site e configurar o Chrome para pular a validação do site para o app, para fins de depuração.

Estabelecer uma associação do app ao site

Abra o arquivo de recursos de string app > res > values > strings.xml e adicione a declaração Digital AssetLinks abaixo:

<resources>
    <string name="app_name">AirHorner Trusted Web Activity</string>
    <string name="asset_statements">
        [{
            \"relation\": [\"delegate_permission/common.handle_all_urls\"],
            \"target\": {
                \"namespace\": \"web\",
                \"site\": \"https://airhorner.com\"}
        }]
    </string>
</resources>

Mude o conteúdo do atributo site para corresponder ao esquema e ao domínio aberto pela atividade confiável da Web.

No arquivo do manifesto do app Android, AndroidManifest.xml, vincule à instrução adicionando uma nova tag meta-data, mas desta vez como uma filha da tag application:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.twa.myapplication">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="asset_statements"
            android:resource="@string/asset_statements" />

        <activity>
            ...
        </activity>

    </application>
</manifest>

Agora estabelecemos uma relação entre o aplicativo Android e o site. É útil depurar essa parte do relacionamento sem criar a validação do site para o aplicativo.

Veja como testar isso em um dispositivo de desenvolvimento:

Ativar o modo de depuração

1. Abra o Chrome no dispositivo de desenvolvimento, navegue até chrome://flags, pesquise um item chamado Ativar a linha de comando em dispositivos sem acesso root e mude para ATIVADO. Em seguida, reinicie o navegador.
2. Em seguida, no aplicativo Terminal do sistema operacional, use a Android Debug Bridge (instalada com o Android Studio) e execute o seguinte comando:

adb shell "echo '_ --disable-digital-asset-link-verification-for-url=\"https://airhorner.com\"' > /data/local/tmp/chrome-command-line"

Feche o Chrome e inicie o aplicativo novamente no Android Studio. O app agora vai aparecer em tela cheia.

Observação: talvez seja necessário forçar o fechamento do Chrome para que ele seja reiniciado com a linha de comando correta. Acesse Configurações do Android > Apps e notificações > Chrome e clique em Forçar fechamento.

Estabelecer uma associação do site ao app

O desenvolvedor precisa coletar duas informações do app para criar a associação:

• Nome do pacote:a primeira informação é o nome do pacote do app. Esse é o mesmo nome de pacote gerado ao criar o app. Ele também pode ser encontrado no Módulo build.gradle, em Gradle Scripts > build.gradle (Module: app), e é o valor do atributo applicationId.
• Impressão digital SHA-256:os aplicativos Android precisam ser assinados para serem enviados para a Play Store. A mesma assinatura é usada para estabelecer a conexão entre o site e o app usando a impressão digital SHA-256 da chave de upload.

A documentação do Android explica em detalhes como gerar uma chave usando o Android Studio. Anote o caminho, o alias e as senhas do keystore, porque você vai precisar deles na próxima etapa.

Extraia a impressão digital SHA-256 usando o keytool, com o seguinte comando:

keytool -list -v -keystore [path] -alias [alias] -storepass [password] -keypass [password]

O valor da impressão digital SHA-256 é impresso na seção Impressões digitais do certificado. Confira um exemplo de saída:

keytool -list -v -keystore ./mykeystore.ks -alias test -storepass password -keypass password

Alias name: key0
Creation date: 28 Jan 2019
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Issuer: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Serial number: ea67d3d
Valid from: Mon Jan 28 14:58:00 GMT 2019 until: Fri Jan 22 14:58:00 GMT 2044
Certificate fingerprints:
   SHA1: 38:03:D6:95:91:7C:9C:EE:4A:A0:58:43:A7:43:A5:D2:76:52:EF:9B
   SHA256: F5:08:9F:8A:D4:C8:4A:15:6D:0A:B1:3F:61:96:BE:C7:87:8C:DE:05:59:92:B2:A3:2D:05:05:A5:62:A5:2F:34
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3

Com essas informações em mãos, acesse o Assetlinks Generator, preencha os campos e clique em Generate Statement. Copie a declaração gerada e a exiba no seu domínio, no URL /.well-known/assetlinks.json.

Observação: o arquivo AssetLinks precisa estar em /.well-known/assetlinks.json, na raiz do domínio, porque é apenas nesse local que o Chrome vai procurar.

Como criar um ícone

Quando o Android Studio cria um novo projeto, ele vem com um ícone padrão. Como desenvolvedor, você vai querer criar seu próprio ícone e diferenciar seu aplicativo dos outros na tela de início do Android.

O Android Studio contém o Image Asset Studio, que oferece as ferramentas necessárias para criar os ícones corretos, para cada resolução e forma que o aplicativo precisa.

No Android Studio, navegue até File > New > Image Asset, selecione Launcher Icons (Adaptative and Legacy) e siga as etapas do assistente para criar um ícone personalizado para o aplicativo.

Como gerar um APK assinado

Com o arquivo assetlinks no lugar no seu domínio e a tag asset_statements configurada no aplicativo Android, a próxima etapa é gerar um app assinado. Novamente, as etapas para isso estão amplamente documentadas.

O APK de saída pode ser instalado em um dispositivo de teste usando o adb:

adb install app-release.apk

Se a etapa de verificação falhar, será possível verificar mensagens de erro usando o Android Debug Bridge, no terminal do SO e com o dispositivo de teste conectado.

adb logcat | grep -e OriginVerifier -e digital_asset_links

Com o APK de upload gerado, agora você pode fazer upload do app na Play Store.

Como adicionar uma tela de apresentação

A partir do Chrome 75, as Trusted Web Activities oferecem suporte a telas de apresentação. A tela de apresentação pode ser configurada adicionando alguns novos arquivos de imagem e configurações ao projeto.

Atualize para o Chrome 75 ou mais recente e use a versão mais recente da Biblioteca de suporte a atividades da Web confiáveis.

Como gerar as imagens para a tela de apresentação

Os dispositivos Android podem ter diferentes tamanhos de tela e densidades de pixels. Para garantir que a tela de apresentação tenha boa aparência em todos os dispositivos, é necessário gerar a imagem para cada densidade de pixels.

Uma explicação completa de pixels independentes da tela (dp ou dip) está fora do escopo deste artigo, mas um exemplo seria criar uma imagem de 320 x 320 dp, que representa um quadrado de 2 x 2 polegadas em uma tela de dispositivo de qualquer densidade e é equivalente a 320 x 320 pixels na densidade mdpi.

A partir daí, podemos derivar os tamanhos necessários para outras densidades de pixels. Confira abaixo uma lista com as densidades de pixels, o multiplicador aplicado ao tamanho base (320 x 320 dp), o tamanho resultante em pixels e o local em que a imagem precisa ser adicionada no projeto do Android Studio.

Densidade	Multiplicador	Tamanho	Localização do projeto
mdpi (baseline)	1x	320x320 px	/res/drawable-mdpi/
ldpi	0,75x	240x240 px	/res/drawable-ldpi/
hdpi	1,5x	480x480 px	/res/drawable-hdpi/
xhdpi	2x	640x640 px	/res/drawable-xhdpi/
xxhdpi	3,0x	960x960 px	/res/drawable-xxhdpi/
xxxhdpi	4,0x	1280 x 1.280 px	/res/drawable-xxxhdpi/

Observação: uma alternativa para criar todos os tamanhos de imagem é usar um drawable vetorial. O Vector Asset Studio oferece ferramentas para ajudar os desenvolvedores a transformar SVGs em drawables vetoriais do Android.

Atualização do aplicativo

Com as imagens da tela de apresentação geradas, é hora de adicionar as configurações necessárias ao projeto.

Primeiro, adicione um content-provider ao manifesto do Android (AndroidManifest.xml).

<application>
    ...
    <provider
        android:name="androidx.core.content.FileProvider"
        android:authorities="com.example.twa.myapplication.fileprovider"
        android:grantUriPermissions="true"
        android:exported="false">
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/filepaths" />
    </provider>
</application>

Observação: mude o atributo android:authorities ao criar o provedor, porque dois aplicativos não podem ter a mesma autoridade em um dispositivo.

Em seguida, adicione o recurso res/xml/filepaths.xml e especifique o caminho para a tela inicial do TWA:

<paths>
    <files-path path="twa_splash/" name="twa_splash" />
</paths>

Por fim, adicione meta-tags ao manifesto do Android para personalizar a LauncherActivity:

<activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">
    ...
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_IMAGE_DRAWABLE"
               android:resource="@drawable/splash"/>
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_BACKGROUND_COLOR"
               android:resource="@color/colorPrimary"/>
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_FADE_OUT_DURATION"
               android:value="300"/>
    <meta-data android:name="android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY"
               android:value="com.example.twa.myapplication.fileprovider"/>
    ...
</activity>

Verifique se o valor da tag android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY corresponde ao valor definido do atributo android:authorities dentro da tag provider.

Tornar a LauncherActivity transparente

Além disso, verifique se a LauncherActivity é transparente para evitar que uma tela branca seja mostrada antes da tela de apresentação. Para isso, defina um tema translúcido para a LauncherActivity:

<application>
    ...
    <activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity"
              android:theme="@android:style/Theme.Translucent.NoTitleBar">
    ...
    </activity>
</application>

Estamos ansiosos para ver o que os desenvolvedores vão criar com as atividades confiáveis na Web. Para enviar feedback, entre em contato com a gente em @ChromiumDev.