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 na Web confiável não exige que os desenvolvedores criem código Java, mas o Android Studio é obrigatório. Este guia foi criado usando o Android Studio 3.3. Consulte os documentos 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 Acessar a biblioteca de Atividade 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 local: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 de 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, que podem ser um pouco confusos, 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 confiável na Web, 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.

Remova 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 de sites e configurar o Chrome para pular o site para a validação de apps para fins de depuração.

Estabelecer uma associação do aplicativo 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>

Já estabelecemos uma relação entre o app 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 seu 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 aplicativo será mostrado 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 entre o site e o app

Há duas informações que o desenvolvedor precisa coletar 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 à 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 path, o alias e as senhas do repositório de chaves, porque você 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 de 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 o lugar em que o Chrome vai procurar ele.

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 no Android Launcher.

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 seu domínio e a tag asset_statements configurada no aplicativo Android, a próxima etapa é gerar um app assinado. Mais uma vez, as etapas para isso sã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, é possível fazer upload do app para a 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 de Atividades Confiáveis na Web.

Como gerar 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 uma boa aparência em todos os dispositivos, é necessário gerar a imagem para cada densidade de pixel.

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)	1,0x	320x320 px	/res/drawable-mdpi/
ldpi	0,75x	240x240 px	/res/drawable-ldpi/
hdpi	1,5x	480x480 px	/res/drawable-hdpi/
xhdpi	2,0x	640x640 px	/res/drawable-xhdpi/
xxhdpi	3x	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 provedor de conteúdo 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 de apresentação 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.