Panduan Integrasi

André Cipriani Bandarra

Catatan: Catatan: Panduan memulai yang lebih sederhana untuk Aktivitas Web Tepercaya kini tersedia.

Menyiapkan Aktivitas Web Tepercaya tidak mengharuskan developer menulis kode Java, tetapi Android Studio diperlukan. Panduan ini dibuat menggunakan Android Studio 3.3. Lihat dokumen tentang cara menginstalnya.

Membuat Project Aktivitas Web Tepercaya

Saat menggunakan Trusted Web Activities, project harus menargetkan API 16 atau yang lebih tinggi.

Catatan: Bagian ini akan memandu Anda menyiapkan project baru di Android Studio. Jika Anda sudah memahami alat ini, silakan lanjutkan ke bagian Mendapatkan Library Aktivitas Web Tepercaya.

Buka Android Studio dan klik Start a new Android Studio project.

Android Studio akan meminta Anda memilih jenis Aktivitas. Karena Aktivitas Web Tepercaya menggunakan Aktivitas yang disediakan oleh library dukungan, pilih Add No Activity, lalu klik Next.

Langkah berikutnya, wizard akan meminta konfigurasi untuk project. Berikut deskripsi singkat dari setiap kolom:

• Nama: Nama yang akan digunakan untuk aplikasi Anda di Peluncur Android.
• Nama Paket: ID unik untuk Aplikasi Android di Play Store dan di perangkat Android. Lihat dokumentasi untuk mengetahui informasi selengkapnya tentang persyaratan dan praktik terbaik untuk membuat nama paket untuk aplikasi Android.
• Save location: Tempat Android Studio akan membuat project dalam sistem file.
• Bahasa: Project ini tidak memerlukan penulisan kode Java atau Kotlin. Pilih Java, sebagai default.
• API Level Minimum: Library Dukungan memerlukan setidaknya API Level 16. Pilih API 16 versi apa pun di atas.

Biarkan kotak centang lainnya tidak dicentang, karena kita tidak akan menggunakan Instant Apps atau artefak AndroidX, lalu klik Finish.

Mendapatkan Support Library Aktivitas Web Tepercaya

Untuk menyiapkan library Aktivitas Web Tepercaya dalam project, Anda harus mengedit file build Aplikasi. Cari bagian Gradle Scripts di Project Navigator. Ada dua file bernama build.gradle, yang mungkin sedikit membingungkan dan deskripsi dalam tanda kurung membantu mengidentifikasi file yang benar.

File yang kita cari adalah file dengan modul Module di samping namanya.

Library Aktivitas Web Tepercaya menggunakan fitur Java 8 dan perubahan pertama mengaktifkan Java 8. Tambahkan bagian compileOptions ke bagian bawah android, seperti di bawah ini:

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

Langkah berikutnya adalah menambahkan Library Dukungan Aktivitas Web Tepercaya ke project. Tambahkan dependensi baru ke bagian dependencies:

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

Android Studio akan menampilkan perintah yang meminta untuk menyinkronkan project sekali lagi. Klik link Sync Now dan sinkronkan.

Meluncurkan Aktivitas Web Tepercaya

Menyiapkan Aktivitas Web Tepercaya dilakukan dengan mengedit Manifes Aplikasi Android.

Di Project Navigator, luaskan bagian app, diikuti dengan manifes, lalu klik dua kali AndroidManifest.xml untuk membuka file.

Karena kita meminta Android Studio untuk tidak menambahkan Aktivitas apa pun ke project saat membuatnya, manifes akan kosong dan hanya berisi tag aplikasi.

Tambahkan Aktivitas Web Tepercaya dengan menyisipkan tag activity ke dalam 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>

Tag yang ditambahkan ke XML adalah Manifes Aplikasi Android standar. Ada dua informasi yang relevan untuk konteks Aktivitas Web Tepercaya:

1. Tag meta-data memberi tahu Aktivitas Web Tepercaya URL yang harus dibuka. Ubah atribut android:value dengan URL PWA yang ingin Anda buka. Dalam contoh ini, nilainya adalah https://airhorner.com.
2. Tag intent-filter kedua memungkinkan Aktivitas Web Tepercaya untuk mencegat Intent Android yang membuka https://airhorner.com. Atribut android:host di dalam tag data harus mengarah ke domain yang dibuka oleh Aktivitas Web Tepercaya.

Catatan: Saat menjalankan project pada tahap ini, Panel URL dari Tab Kustom akan tetap ditampilkan di bagian atas layar. Ini bukan bug.

Bagian berikutnya akan menunjukkan cara menyiapkan Digital AssetLinks untuk memverifikasi hubungan antara situs dan aplikasi, serta menghapus panel URL.

Menghapus panel URL

Aktivitas Web Tepercaya memerlukan pengaitan antara aplikasi Android dan situs yang akan dibuat untuk menghapus kolom URL.

Pengaitan ini dibuat melalui Digital Asset Links dan pengaitan harus dibuat dengan kedua cara, yaitu dengan menautkan dari aplikasi ke situs dan dari situs ke aplikasi.

Anda dapat menyiapkan validasi aplikasi ke situs dan menyiapkan Chrome untuk melewati validasi situs ke aplikasi, untuk tujuan proses debug.

Membuat pengaitan dari aplikasi ke situs

Buka file resource string app > res > values > strings.xml dan tambahkan pernyataan Digital AssetLinks di bawah:

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

Ubah konten untuk atribut site agar cocok dengan skema dan domain yang dibuka oleh Aktivitas Web Tepercaya.

Kembali ke file Manifes Aplikasi Android, AndroidManifest.xml, tautkan ke pernyataan dengan menambahkan tag meta-data baru, tetapi kali ini sebagai turunan dari 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>

Sekarang kita telah membuat hubungan dari aplikasi Android ke situs. Sebaiknya debug bagian hubungan ini tanpa membuat validasi situs ke aplikasi.

Berikut cara mengujinya di perangkat pengembangan:

Mengaktifkan mode debug

1. Buka Chrome di perangkat pengembangan, buka chrome://flags, telusuri item yang disebut Enable command line on non-rooted devices dan ubah menjadi ENABLED, lalu mulai ulang browser.
2. Selanjutnya, di aplikasi Terminal sistem operasi Anda, gunakan Android Debug Bridge (diinstal dengan Android Studio), dan jalankan perintah berikut:

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

Tutup Chrome dan luncurkan kembali aplikasi Anda dari Android Studio. Aplikasi sekarang akan ditampilkan dalam layar penuh.

Catatan: Anda mungkin perlu menutup paksa Chrome agar dimulai ulang dengan command line yang benar. Buka Setelan Android > Aplikasi & notifikasi > Chrome, lalu klik Paksa berhenti.

Membuat pengaitan dari situs ke aplikasi

Ada 2 informasi yang perlu dikumpulkan developer dari aplikasi untuk membuat pengaitan:

• Nama Paket: Informasi pertama adalah nama paket untuk aplikasi. Ini adalah nama paket yang sama yang dihasilkan saat membuat aplikasi. Nama paket juga dapat ditemukan di dalam Modul build.gradle, di bagian Gradle Scripts > build.gradle (Module: app), dan merupakan nilai atribut applicationId.
• Sidik Jari SHA-256: Aplikasi Android harus ditandatangani agar dapat diupload ke Play Store. Tanda tangan yang sama digunakan untuk membuat koneksi antara situs dan aplikasi melalui sidik jari SHA-256 kunci upload.

Dokumentasi Android menjelaskan secara mendetail cara membuat kunci menggunakan Android Studio. Pastikan untuk mencatat jalur, alias, dan sandi untuk keystore, karena Anda akan memerlukannya untuk langkah berikutnya.

Ekstrak sidik jari SHA-256 menggunakan keytool, dengan perintah berikut:

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

Nilai untuk sidik jari SHA-256 dicetak di bagian sidik jari Sertifikat. Berikut adalah contoh output:

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

Setelah memiliki kedua informasi tersebut, buka generator assetlinks, isi kolom, lalu klik Buat Pernyataan. Salin pernyataan yang dihasilkan dan tayangkan dari domain Anda, dari URL /.well-known/assetlinks.json.

Catatan: File AssetLinks harus berada di /.well-known/assetlinks.json, di root domain, karena hanya di sana Chrome akan mencarinya.

Membuat Ikon

Saat membuat project baru, Android Studio akan menyertakan Ikon default. Sebagai developer, Anda perlu membuat ikon sendiri dan membedakan aplikasi dari yang lain di Peluncur Android.

Android Studio berisi Image Asset Studio, yang menyediakan alat yang diperlukan untuk membuat ikon yang benar, untuk setiap resolusi dan membentuk kebutuhan aplikasi Anda.

Di dalam Android Studio, buka File > New > Image Asset, pilih Launcher Icons (Adaptative and Legacy), lalu ikuti langkah-langkah dari Wizard. untuk membuat ikon kustom untuk aplikasi.

Membuat APK yang ditandatangani

Dengan file assetlinks yang ada di domain Anda dan tag asset_statements yang dikonfigurasi di aplikasi Android, langkah berikutnya adalah membuat aplikasi yang ditandatangani. Sekali lagi, langkah-langkah untuk ini telah banyak didokumentasikan.

APK output dapat diinstal ke perangkat pengujian, menggunakan adb:

adb install app-release.apk

Jika langkah verifikasi gagal, Anda dapat memeriksa pesan error menggunakan Android Debug Bridge, dari terminal OS dan dengan perangkat pengujian yang terhubung.

adb logcat | grep -e OriginVerifier -e digital_asset_links

Dengan APK upload yang dihasilkan, Anda kini dapat mengupload aplikasi ke Play Store.

Menambahkan Layar Pembuka

Mulai Chrome 75, Aktivitas Web Tepercaya memiliki dukungan untuk Layar Pembuka. Layar Pembuka dapat disiapkan dengan menambahkan beberapa file gambar dan konfigurasi baru ke project.

Pastikan untuk mengupdate ke Chrome 75 atau yang lebih baru dan menggunakan Trusted Web Activity Support Library versi terbaru.

Membuat gambar untuk Layar Pembuka

Perangkat Android dapat memiliki ukuran layar dan kepadatan piksel yang berbeda. Untuk memastikan Layar Mulai terlihat bagus di semua perangkat, Anda harus membuat gambar untuk setiap kepadatan piksel.

Penjelasan lengkap tentang piksel independen tampilan (dp atau dip) di luar cakupan artikel ini, tetapi salah satu contohnya adalah membuat gambar yang berukuran 320x320 dp, yang mewakili persegi 2x2 inci di layar perangkat dengan kepadatan apa pun dan setara dengan 320x320 piksel pada kepadatan mdpi.

Dari sana, kita dapat memperoleh ukuran yang diperlukan untuk kepadatan piksel lainnya. Berikut adalah daftar dengan kepadatan piksel, pengganda yang diterapkan ke ukuran dasar (320x320dp), ukuran yang dihasilkan dalam piksel, dan lokasi tempat gambar harus ditambahkan di project Android Studio.

Kepadatan	Pengganda	Ukuran	Lokasi Project
mdpi (dasar pengukuran)	1,0x	320x320 piksel	/res/drawable-mdpi/
ldpi	0,75x	240x240 piksel	/res/drawable-ldpi/
hdpi	1,5x	480x480 piksel	/res/drawable-hdpi/
xhdpi	2,0x	640x640 piksel	/res/drawable-xhdpi/
xxhdpi	3,0x	960x960 piksel	/res/drawable-xxhdpi/
xxxhdpi	4,0x	1280x1280 piksel	/res/drawable-xxxhdpi/

Catatan: Alternatif untuk membuat semua ukuran gambar adalah menggunakan satu Vektor Drawable. Vector Asset Studio menawarkan alat untuk membantu developer mengubah SVG menjadi Vektor Drawable Android.

Mengupdate aplikasi

Setelah gambar untuk layar pembuka dibuat, saatnya menambahkan konfigurasi yang diperlukan ke project.

Pertama, tambahkan content-provider ke Manifes 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>

Catatan: Pastikan untuk mengubah atribut android:authorities saat membuat penyedia, karena dua aplikasi tidak dapat memiliki otorisasi yang sama di perangkat.

Kemudian, tambahkan resource res/xml/filepaths.xml, dan tentukan jalur ke layar pembuka twa:

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

Terakhir, tambahkan meta-tags ke Manifes Android untuk menyesuaikan 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>

Pastikan nilai tag android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY cocok dengan nilai yang ditentukan dari atribut android:authorities di dalam tag provider.

Membuat LauncherActivity transparan

Selain itu, pastikan LauncherActivity transparan untuk menghindari layar putih yang ditampilkan sebelum layar pembuka dengan menetapkan tema transparan untuk LauncherActivity:

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

Kami menantikan apa yang akan dibuat developer dengan Aktivitas Web Tepercaya. Untuk memberikan masukan, hubungi kami di @ChromiumDev.