Przewodnik integracji

André Cipriani Bandarra
André Cipriani Bandarra

Skonfigurowanie zaufanej aktywności w internecie nie wymaga od programistów tworzenia kodu w języku Java, ale potrzebna jest usługa Android Studio. Ten przewodnik został utworzony w Android Studio 3.3. Zapoznaj się z dokumentacją dotyczącą jej instalowania.

Utwórz projekt zaufanej aktywności internetowej

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

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

Android Studio poprosi o wybranie typu aktywności. Ponieważ zaufane aktywności internetowe korzystają z aktywności udostępnionej przez bibliotekę pomocy, wybierz Dodaj brak aktywności i kliknij Dalej.

W następnym kroku kreator zapyta o konfiguracje projektu. Oto krótki opis każdego pola:

  • Nazwa: nazwa, która będzie używana w aplikacji w programie uruchamiającym 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 dotyczących tworzenia nazw pakietów dla aplikacji na Androida znajdziesz w dokumentacji.
  • Zapisz lokalizację:miejsce, w którym Android Studio utworzy projekt w systemie plików.
  • Język: projekt nie wymaga pisania żadnego kodu w języku Java ani Kotlin. Domyślnie wybierz Java.
  • Minimalny poziom API: biblioteka pomocy wymaga co najmniej poziomu API 16. Wybierz API 16 w dowolnej wersji powyżej.

Pozostałe pola wyboru pozostaw niezaznaczone, ponieważ nie będziemy używać aplikacji błyskawicznych ani artefaktów AndroidaX, a potem kliknij Zakończ.

Pobierz bibliotekę pomocy dla zaufanych aktywności w internecie

Aby skonfigurować bibliotekę Zaufanej aktywności internetowej w projekcie, musisz zmodyfikować plik kompilacji aplikacji. Znajdź sekcję Skrypty Gradle w Nawigatorze projektów. Istnieją dwa pliki o nazwie build.gradle, co może być mylące, a opisy w nawiasach pomagają zidentyfikować właściwy plik.

Szukamy pliku, który ma obok nazwy moduł Module.

Biblioteka zaufanych aktywności internetowych korzysta z funkcji Java 8, a pierwsza zmiana to Java 8. Dodaj sekcję compileOptions na dole sekcji android, jak poniżej:

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

Następnym krokiem będzie dodanie do projektu biblioteki pomocy dla zaufanych aktywności w internecie. Dodaj nową zależność do sekcji dependencies:

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

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

Uruchamianie zaufanej aktywności internetowej

Aby skonfigurować Zaufaną aktywność w internecie, użyj edycji pliku manifestu aplikacji na Androida.

W Project Navigator rozwiń sekcję app, a następnie pliki manifestu, a następnie kliknij dwukrotnie AndroidManifest.xml, aby otworzyć plik.

Ponieważ poprosiliśmy Android Studio, aby nie dodawać żadnej aktywności do projektu podczas jego tworzenia, plik manifestu jest pusty i zawiera tylko tag aplikacji.

Dodaj zaufaną aktywność internetową, 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 to standardowy plik manifestu aplikacji na Androida. W kontekście zaufanych działań w internecie dostępne są 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 wewnątrz tagu data musi wskazywać domenę otwieraną przez zaufaną aktywność internetową.

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

Usuń pasek adresu URL

Zaufane działania internetowe wymagają powiązania między aplikacją na Androida a witryną w celu usunięcia paska adresu URL.

Powiązanie można utworzyć za pomocą linków do zasobów cyfrowych. Trzeba je utworzyć na oba sposoby, łącząc aplikację z witryną oraz witrynę z aplikacją.

Aplikację można skonfigurować pod kątem weryfikacji witryny, a w Chrome tak, aby na potrzeby debugowania pomijała tę witrynę.

Otwórz plik zasobów ciągu app > res > values > strings.xml i dodaj poniżej instrukcję 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 zaufaną aktywność internetową.

Wróć do pliku manifestu aplikacji na Androida (AndroidManifest.xml) i dodaj link do instrukcji przez dodanie nowego tagu meta-data, ale tym razem jako elementu podrzędnego 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>

Nawiązaliśmy połączenie między aplikacją na Androida a witryną. Warto debugować tę część relacji bez tworzenia walidacji witryny do aplikacji.

Aby to sprawdzić na urządzeniu, którego używasz do programowania:

Włączanie trybu debugowania

  1. Otwórz Chrome na urządzeniu, z którego korzystasz, przejdź do chrome://flags, wyszukaj element o nazwie Włącz wiersz poleceń na urządzeniach bez dostępu do roota, zmień go na ENABLED (Włączona), a następnie ponownie uruchom przeglądarkę.
  2. Następnie w aplikacji Terminal systemu operacyjnego użyj Android Debug Bridge (zainstalowanego w 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 uruchom ponownie aplikację z poziomu Android Studio. Aplikacja powinna wyświetlić się na pełnym ekranie.

Aby możliwe było utworzenie powiązania, deweloper musi zebrać z aplikacji 2 informacje:

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

W dokumentacji Androida szczegółowo wyjaśniamy, jak wygenerować klucz za pomocą Android Studio. Zapisz ś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ładowe dane wyjściowe:

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

Mając pod ręką oba te informacje, przejdź do generatora linków do materiałów typuassetlink, wypełnij pola i kliknij Wygeneruj twierdzenie. Skopiuj wygenerowaną instrukcję i wyświetl ją ze swojej domeny pod adresem URL /.well-known/assetlinks.json.

Tworzenie ikony

Gdy Android Studio tworzy nowy projekt, ma domyślną ikonę. Jako programista warto utworzyć własną ikonę w programie Android Launcher, aby wyróżnić ją na tle innych aplikacji.

Android Studio zawiera narzędzie Image Asset Studio, które zawiera narzędzia niezbędne do tworzenia prawidłowych ikon odpowiednich do każdej rozdzielczości i dostosowanych do potrzeb aplikacji.

W Android Studio przejdź do File > New > Image Asset, wybierz Launcher Icons (Adaptative and Legacy) i postępuj zgodnie z instrukcjami w kreatorze, aby utworzyć niestandardową ikonę aplikacji.

Generowanie podpisanego pakietu APK

Po umieszczeniu pliku assetlinks w domenie i skonfigurowaniu tagu asset_statements w aplikacji na Androida należy wygenerować podpisaną aplikację. Czynności, które należy wykonać, aby tak się stało, są udokumentowane.

Wyjściowy plik APK można zainstalować na urządzeniu testowym za pomocą narzędzia adb:

adb install app-release.apk

Jeśli etap weryfikacji się nie powiedzie, komunikaty o błędach możesz sprawdzić za pomocą Android Debug Bridge, w terminalu systemu operacyjnego i po podłączeniu urządzenia testowego.

adb logcat | grep -e OriginVerifier -e digital_asset_links

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

Dodawanie ekranu powitalnego

Od 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 Chrome do wersji 75 lub nowszej i użyj najnowszej wersji biblioteki obsługi Zaufanej aktywności w internecie.

Generuję obrazy dla ekranu powitalnego

Urządzenia z Androidem mogą mieć różne rozmiary ekranu i gęstość pikseli. Aby mieć pewność, że ekran powitalny będzie wyglądał dobrze na wszystkich urządzeniach, musisz wygenerować taki 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. Przykładem może być stworzenie obrazu o wymiarach 320 x 320 dp, co odpowiada kwadratowi 2 x 2 cali na ekranie urządzenia o dowolnej gęstości i odpowiada rozdzielczości 320 x 320 pikseli przy gęstości mdpi.

Na podstawie tych danych możemy określić rozmiary potrzebne do obsługi innych gęstości pikseli. Poniżej znajduje się lista gęstości pikseli, mnożnika zastosowanego do rozmiaru podstawowego (320 x 320 dp), wynikowego rozmiaru w pikselach oraz lokalizacji, w której należy dodać obraz w projekcie Android Studio.

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

Aktualizowanie aplikacji

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

Najpierw do pliku manifestu Androida (AndroidManifest.xml) dodaj właściwość content-provider.

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

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

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

Na koniec dodaj meta-tags do pliku manifestu Androida, 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 odpowiada wartości zdefiniowanej w atrybucie android:authorities w tagu provider.

Przejrzystość LauncherActivity

Dodatkowo upewnij się, że LauncherActivity jest przezroczysty, aby przed ekranem nie wyświetlał się biały ekran. 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 budują za pomocą zaufanych aktywności internetowych. Jeśli chcesz podzielić się z nami opinią, napisz do nas na adres @ChromiumDev.