Przewodnik integracji

André Cipriani Bandarra

Uwaga: prostszy szybki przewodnik po zaufanych działaniach w internecie jest już dostępny.

Konfigurowanie zaufanej aktywności w internecie nie wymaga od deweloperów pisania kodu Java, ale wymaga użycia Android Studio. Ten przewodnik został utworzony w wersji Android Studio 3.3. Więcej informacji o instalowaniu znajdziesz w dokumentacji.

Tworzenie projektu zaufana aktywność internetowa

Jeśli korzystasz z zaufanych działań w internecie, projekt musi być kierowany na interfejs API na poziomie 16 lub wyższym.

Uwaga: w tej sekcji znajdziesz instrukcje konfigurowania nowego projektu w Android Studio. Jeśli znasz już to narzędzie, możesz przejść bezpośrednio do sekcji Pozyskiwanie zaufanej biblioteki aktywności w internecie.

Otwórz Android Studio i kliknij Start a new Android Studio project (Rozpocznij nowy projekt w Android Studio).

Android Studio wyświetli prośbę o wybranie typu aktywności. Zaufane aktywności w internecie korzystają z aktywności udostępnionej przez bibliotekę komponentów, dlatego wybierz Dodaj brak aktywności i kliknij Dalej.

W kolejnych krokach kreator poprosi o skonfigurowanie projektu. Oto krótki opis każdego pola:

• Nazwa: nazwa, która będzie używana dla aplikacji w Menu z aplikacjami na Androida.
• Nazwa pakietu: unikalny identyfikator aplikacji na Androida w Sklepie Play i na urządzeniach z Androidem. Więcej informacji o wymaganiach i sprawdzonych metodach tworzenia nazw pakietów aplikacji na Androida znajdziesz w dokumentacji.
• Lokalizacja zapisu: miejsce, w którym Android Studio utworzy projekt w systemie plików.
• Język: projekt nie wymaga pisania kodu Java ani Kotlin. Wybierz Java jako domyślną.
• Minimalny poziom interfejsu API: Biblioteka pomocy wymaga co najmniej poziomu API 16. Wybierz interfejs API 16 lub nowszą wersję.

Pozostaw niezaznaczone pozostałe pola wyboru, ponieważ nie będziemy używać aplikacji błyskawicznych ani artefaktów AndroidX. Następnie kliknij Zakończ.

Pobieranie biblioteki obsługi zaufanej aktywności internetowej

Aby skonfigurować bibliotekę Trusted Web Activity w projekcie, musisz edytować plik kompilacji aplikacji. W Nawigacji po projekcie odszukaj sekcję Skrypty Gradle. Występują 2 pliki o nazwie build.gradle, co może być mylące, a opisy w nawiasach ułatwiają znalezienie właściwego z nich.

Szukany plik to ten, obok którego nazwy znajduje się moduł Module.

Biblioteka zaufanych działań internetowych korzysta z funkcji Javy 8, a pierwsza zmiana umożliwia korzystanie z tej wersji. Dodaj sekcję compileOptions na dole sekcji android, jak pokazano poniżej:

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

Następnym krokiem będzie dodanie do projektu biblioteki obsługi zaufanej aktywności w internecie. Dodaj nowe zależności do sekcji dependencies:

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

Android Studio wyświetli prośbę o ponowne zsynchronizowanie projektu. Kliknij link Synchronizuj teraz i zsynchronizuj.

Uruchamianie zaufanej aktywności w internecie

Konfigurowanie zaufanej aktywności w internecie odbywa się poprzez edytowanie pliku manifestu aplikacji na Androida.

W Nawigatorze projektu rozwiń sekcję aplikacja, a potem pliki manifestu i kliknij dwukrotnie AndroidManifest.xml, aby otworzyć plik.

Ponieważ poprosiliśmy Android Studio o niedodawanie do naszego projektu żadnych czynności podczas jego tworzenia, manifest jest pusty i zawiera tylko tag aplikacji.

Dodaj zaufane działanie w internecie, wstawiając tag activity do tagu 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>

Tagi dodane do pliku XML są standardowymi tagami pliku manifestu aplikacji na Androida. W kontekście zaufanych aktywności w internecie wyróżniamy 2 rodzaje informacji:

1. Tag meta-data informuje zaufaną aktywność internetową, który adres URL ma otworzyć. Zmień atrybut android:value na adres URL aplikacji PWA, którą chcesz otworzyć. W tym przykładzie jest to https://airhorner.com.
2. Drugi tag intent-filter umożliwia zaufanej aktywności internetowej przechwytywanie intencji Androida, które otwierają https://airhorner.com. Atrybut android:host w tagu data musi wskazywać domenę otwieraną przez zaufaną aktywność internetową.

Uwaga: gdy uruchomisz projekt na tym etapie, pasek adresu z kart niestandardowych będzie nadal widoczny u góry ekranu. To nie jest błąd.

W następnej sekcji pokażemy, jak skonfigurować Digital AssetLinks, aby zweryfikować relację między witryną a aplikacją, i jak usunąć pasek adresu URL.

Usuwanie paska adresu URL

Aby usunąć pasek adresu URL, zaufana aktywność w internecie wymaga powiązania aplikacji na Androida z witryną.

Powiązanie to jest tworzone za pomocą protokołu Digital Asset Links. Powiązanie musi być tworzone w obu kierunkach: z aplikacji do witryny i z witryny do aplikacji.

W celu debugowania możesz skonfigurować aplikację tak, aby sprawdzała stronę internetową, oraz skonfigurować Chrome tak, aby pomijała sprawdzanie strony internetowej i aplikacji.

Tworzenie powiązania aplikacji z witryną

Otwórz plik zasobów ciągu znaków app > res > values > strings.xml i dodaj poniższe oświadczenie Digital AssetLinks:

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

Zmień zawartość atrybutu site, aby pasowała do schematu i domeny otwartej przez zaufany proces w przeglądarce.

W pliku manifestu aplikacji na Androida AndroidManifest.xml dodaj link do oświadczenia, dodając nowy tag meta-data, ale tym razem jako element podrzędny tagu 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>

Utworzyliśmy już relację między aplikacją na Androida a witryną. Warto debugować tę część relacji bez tworzenia weryfikacji między witryną a aplikacją.

Oto jak przetestować to na urządzeniu deweloperskim:

Włącz tryb debugowania

1. Otwórz Chrome na urządzeniu, którego używasz do programowania, wejdź na chrome://flags, wyszukaj element o nazwie Włącz wiersz poleceń na urządzeniach bez dostępu do roota i zmień go na WŁĄCZONE, a następnie ponownie uruchom przeglądarkę.
2. Następnie w aplikacji Terminal w systemie operacyjnym uruchom Android Debug Bridge (zainstalowany wraz z Android Studio) i uruchom to polecenie:

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

Zamknij Chrome i ponownie uruchom aplikację z Android Studio. Aplikacja powinna się teraz wyświetlić na pełnym ekranie.

Uwaga: może być konieczne przymusowe zamknięcie Chrome, aby można było uruchomić je ponownie z poprawnym wierszem poleceń. Kliknij Ustawienia Androida > Aplikacje i powiadomienia > Chrome, a następnie Wymuś zatrzymanie.

Tworzenie powiązania witryny z aplikacją

Aby utworzyć powiązanie, deweloper musi pobrać 2 informacje z aplikacji:

• Nazwa pakietu: pierwsza informacja to nazwa pakietu aplikacji. Jest to ta sama nazwa pakietu wygenerowana podczas tworzenia aplikacji. Możesz ją też znaleźć w module build.gradle, w sekcji Skrypty Gradle > build.gradle (Moduł: aplikacja). Jest to wartość atrybutu applicationId.
• Odcisk cyfrowy SHA-256: aplikacje na Androida muszą być podpisane, aby można je było przesłać do Sklepu Play. Ten sam podpis jest używany do nawiązywania połączenia między witryną a aplikacją za pomocą odcisku cyfrowego SHA-256 klucza przesyłania.

W dokumentacji Androida znajdziesz szczegółowe informacje o generowaniu klucza za pomocą Android Studio. Zanotuj ścieżkę, alias i hasła do magazynu kluczy, ponieważ będą potrzebne w kolejnym kroku.

Wyodrębnij odcisk cyfrowy SHA-256 za pomocą narzędzia keytool za pomocą tego polecenia:

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

Wartość odcisku cyfrowego SHA-256 jest wydrukowana w sekcji odcisków cyfrowych certyfikatu. Oto przykładowy wynik:

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

Gdy masz już te informacje, otwórz generator assetlinks, wypełnij pola i kliknij Wygeneruj oświadczenie. Skopiuj wygenerowane oświadczenie i wyświetl je z domeny, z adresu URL /.well-known/assetlinks.json.

Uwaga: plik AssetLinks musi znajdować się w /.well-known/assetlinks.json, w katalogu głównym domeny, ponieważ Chrome będzie go tam szukać.

Tworzenie ikony

Gdy Android Studio utworzy nowy projekt, będzie on zawierać domyślną ikonę. Jako deweloper musisz utworzyć własną ikonę, aby odróżnić swoją aplikację od innych w wyszukiwarce Androida.

Android Studio zawiera Image Asset Studio, które udostępnia narzędzia potrzebne do tworzenia prawidłowych ikon w każdej rozdzielczości i kształcie wymaganym przez aplikację.

W Android Studio otwórz File > New > Image Asset, wybierz Launcher Icons (Adaptative and Legacy) i postępuj zgodnie z instrukcjami kreatora, aby utworzyć niestandardową ikonę aplikacji.

Generowanie podpisanego pakietu APK

Po skonfigurowaniu pliku assetlinks w domenie i skonfigurowaniu tagu asset_statements w aplikacji na Androida kolejnym krokiem jest wygenerowanie podpisanej aplikacji. Powtórzę kroki, które trzeba wykonać, są szeroko udokumentowane.

Plik APK wyjściowy można zainstalować na urządzeniu testowym za pomocą adb:

adb install app-release.apk

Jeśli weryfikacja się nie powiedzie, można sprawdzić, czy nie ma komunikatów o błędach, za pomocą Android Debug Bridge, z terminala systemu operacyjnego i połączonego urządzenia testowego.

adb logcat | grep -e OriginVerifier -e digital_asset_links

Po wygenerowaniu pliku APK możesz przesłać aplikację do Sklepu Play.

Dodawanie ekranu powitalnego

Od wersji Chrome 75 zaufane aktywności internetowe obsługują ekrany powitalne. Ekran powitalny można skonfigurować, dodając do projektu kilka nowych plików graficznych i konfiguracji.

Zaktualizuj przeglądarkę do wersji Chrome 75 lub nowszej i używaj najnowszej wersji biblioteki Trusted Web Activity Support Library.

Generuję obrazy na ekran powitalny

Urządzenia z Androidem mogą mieć różne rozmiary ekranu i gęstość pikseli. Aby mieć pewność, że ekran powitalny będzie dobrze wyglądać na wszystkich urządzeniach, musisz wygenerować obraz dla każdej gęstości pikseli.

Pełne wyjaśnienie pikseli niezależnych od wyświetlacza (dp lub dip) wykracza poza zakres tego artykułu, ale przykładem może być utworzenie obrazu o wymiarach 320 x 320 dp, który odpowiada kwadratowi o wymiarach 2 x 2 cale na ekranie urządzenia o dowolnej gęstości i jest równoważny 320 x 320 pikseli przy gęstości mdpi.

Na tej podstawie możemy określić rozmiary potrzebne do innych gęstości pikseli. Poniżej znajduje się lista z gęstościami pikseli, mnożnikiem zastosowanym do rozmiaru podstawowego (320 x 320 dp), uzyskanym rozmiarem w pikselach oraz lokalizacją, w której obraz powinien zostać dodany w projekcie Android Studio.

Gęstość	Mnożnik	Rozmiar	Lokalizacja projektu
mdpi (wartość domyślna)	1x	320 x 320 pikseli	/res/drawable-mdpi/
ldpi	0,75x	240 x 240 pikseli	/res/drawable-ldpi/
HDI	1,5x	480 x 480 pikseli	/res/drawable-hdpi/
xhdpi	2x	640 x 640 pikseli	/res/drawable-xhdpi/
xxhdpi	3,0x	960 x 960 pikseli	/res/drawable-xxhdpi/
xxxhdpi	4×	1280 x 1280 piks.	/res/drawable-xxxhdpi/

Uwaga: alternatywą dla tworzenia wszystkich rozmiarów obrazów jest użycie jednego elementu wektorowego. Vector Asset Studio oferuje narzędzia, które ułatwiają deweloperom przekształcanie plików SVG w obiekty rysowalne wektorowo dla urządzeń z Androidem.

Aktualizowanie aplikacji

Po wygenerowaniu obrazów ekranu powitalnego możesz dodać do projektu niezbędne konfiguracje.

Najpierw dodaj element content-provider do pliku manifestu Androida (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>

Uwaga: pamiętaj o zmianie atrybutu android:authorities podczas tworzenia dostawcy, ponieważ 2 aplikacje nie mogą mieć takich samych uprawnień na urządzeniu.

Następnie dodaj zasób res/xml/filepaths.xml i wskaż ścieżkę do ekranu powitalnego TWA:

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

Na koniec dodaj do pliku AndroidManifest meta-tags, aby dostosować 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>

Upewnij się, że wartość tagu android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY jest zgodna z wartością zdefiniowaną w atrybucie android:authorities w tagu provider.

Ustawianie przezroczystości LauncherActivity

Upewnij się też, że LauncherActivity jest przezroczysty, aby uniknąć wyświetlania białego ekranu przed powitaniem. Aby to zrobić, ustaw półprzezroczysty motyw dla LauncherActivity:

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

Z niecierpliwością czekamy na to, co deweloperzy stworzą dzięki zaufanym działaniom w przeglądarce. Aby podzielić się z nami opinią, napisz do nas na adres @ChromiumDev.