Guia de integração

André Cipriani Bandarra
André Cipriani Bandarra

Configurar uma Atividade confiável na Web 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 para saber como fazer a instalação.

Criar um projeto confiável de atividade na Web

Ao usar Atividades confiáveis na Web, o projeto precisa ter o nível desejado da API 16 ou mais recente.

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

O Android Studio vai solicitar a escolha de um tipo de atividade. Como as Atividades confiáveis na Web usam uma atividade fornecida pela Biblioteca de Suporte, escolha Add No Activity e clique em Next.

Na próxima etapa, o assistente solicitará configurações do projeto. Veja uma breve descrição de cada campo:

  • Nome:o nome que será usado para seu app no Android Launcher.
  • Nome do pacote:um identificador exclusivo para aplicativos Android na Play Store e em dispositivos Android. Confira a documentação para mais informações sobre requisitos e práticas recomendadas para a criação de nomes de pacotes para apps Android.
  • Save location:onde o Android Studio criará o projeto no sistema de arquivos.
  • Linguagem:o projeto não requer código Java ou Kotlin. Selecione Java como padrão.
  • Nível mínimo de API:a Biblioteca de Suporte requer pelo menos o nível 16 da API. Selecione a API 16 em qualquer versão acima.

Deixe as outras caixas de seleção desmarcadas, já que não vamos usar Instant Apps ou artefatos AndroidX, e clique em Finish.

Instalar a Biblioteca de Suporte Confiável na Web

Para configurar a biblioteca de Atividades Confiáveis na Web no projeto, edite 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 Atividades confiáveis na Web 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 mostrado abaixo:

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

A próxima etapa vai adicionar a Biblioteca de Suporte de Atividades Confiáveis na Web 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 faça a sincronização.

Iniciar a Atividade confiável na Web

Para configurar a Atividade confiável na Web, edite o manifesto do app Android.

No Navegador do projeto, expanda a seção app, seguida pelos manifestos e clique duas vezes em AndroidManifest.xml para abrir o arquivo.

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

Adicione a Atividade confiável na Web 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 de atividades confiáveis na Web:

  1. A tag meta-data informa à Atividade na Web Confiável qual URL ela precisa 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 na Web confiável 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.

A próxima seção mostra 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

Para remover a barra de URL, as atividades confiáveis na Web exigem que uma associação entre o aplicativo Android e o site seja estabelecida.

Essa associação é criada pelos Digital Asset Links e precisa ser estabelecida das duas maneiras, vinculando do app ao site e do site ao app.

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

Abra o arquivo de recursos de string app > res > values > strings.xml e adicione a instruçã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>

Altere o conteúdo do atributo site para corresponder ao esquema e ao domínio abertos pela Atividade confiável na Web.

De volta ao arquivo de manifesto do app Android, AndroidManifest.xml, vincule à instrução adicionando uma nova tag meta-data, mas desta vez como 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 aplicativo Android e o site. É útil depurar essa parte do relacionamento sem criar o site para a validação do aplicativo.

Faça o seguinte para testar isso em um dispositivo de desenvolvimento:

Ativar o modo de depuração

  1. Abra o Chrome no dispositivo de desenvolvimento, acesse chrome://flags, procure um item chamado Enable command line on non-root devices e altere-o para ATIVADO e reinicie o navegador.
  2. Em seguida, no aplicativo de terminal do seu sistema operacional, use o Android Debug Bridge (instalado 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 reinicie o app pelo Android Studio. O aplicativo será exibido em tela cheia.

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

  • Package Name:a primeira informação é o nome do pacote do app. É o mesmo nome de pacote gerado na criação do app. Ela também pode ser encontrada no Module build.gradle, em Gradle Scripts > build.gradle (Module: app), e é o valor do atributo applicationId.
  • Impressão digital SHA-256:os apps Android precisam ser assinados para ser enviados à Play Store. A mesma assinatura é usada para estabelecer a conexão entre o site e o app pela 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, alias e passwords do repositório de chaves, 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 aparece na seção de impressões digitais 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 duas informações em mãos, acesse o gerador de assetlinks, preencha os campos e pressione Generate Statement. Copie e veicule a instrução gerada no seu domínio, no URL /.well-known/assetlinks.json.

Como criar um ícone

Quando o Android Studio criar um novo projeto, um ícone padrão vai aparecer nele. Como desenvolvedor, é recomendável criar seu próprio ícone e diferenciar seu aplicativo de outros no Android Launcher.

O Android Studio contém o Image Asset Studio, que oferece as ferramentas necessárias para criar os ícones corretos de acordo com as resoluções e formas do app.

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 aplicativo assinado. De novo, as etapas para isso foram 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, é possível procurar mensagens de erro usando o Android Debug Bridge, do 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, você pode fazer upload do app na Play Store.

Adicionar uma tela de apresentação

A partir do Chrome 75, as Atividades confiáveis na Web oferecem suporte a telas de apresentação. A tela de apresentação pode ser configurada adicionando alguns arquivos de imagem e configurações novos 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.

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 sobre pixels independentes de tela (dp ou dip) está além 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 equivale a 320 x 320 pixels na densidade mdpi.

A partir daí, é possível derivar os tamanhos necessários para outras densidades de pixel. 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 será adicionada ao projeto do Android Studio.

Densidade Multiplicador Tamanho Localização do projeto
mdpi (linha de base) 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 3,0x 960x960 px /res/drawable-xxhdpi/
xxxhdpi 4,0x 1.280 x 1.280 px /res/drawable-xxxhdpi/

Como atualizar o aplicativo

Depois de gerar as imagens para a tela de apresentação, é 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>

Em seguida, adicione o recurso res/xml/filepaths.xml e especifique o caminho para a tela de apresentação:

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

Como tornar a LauncherActivity transparente

Além disso, verifique se a LauncherActivity é transparente para evitar que uma tela branca seja exibida antes da apresentação, definindo 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 criarão com Atividades confiáveis na Web. Para enviar feedback, entre em contato conosco em @ChromiumDev.