Entegrasyon Kılavuzu

André Cipriani Bandarra

Not: Not: Güvenilir Web Etkinlikleri için daha basit bir hızlı başlangıç kılavuzu kullanıma sunuldu.

Güvenilir Web Etkinliği oluşturmak için geliştiricilerin Java kodu yazması gerekmez ancak Android Studio gereklidir. Bu kılavuz, Android Studio 3.3 kullanılarak oluşturulmuştur. Yüklemeyle ilgili dokümanları inceleyin.

Güvenilir Web Etkinliği projesi oluşturma

Güvenilir Web Etkinlikleri kullanılırken projenin API 16 veya sonraki sürümleri hedeflemesi gerekir.

Not: Bu bölümde, Android Studio'da yeni bir proje oluşturma hakkında bilgi verilmektedir. Aracı zaten biliyorsanız Güvenilir Web Etkinliği Kitaplığı'nı edinme bölümüne atlayabilirsiniz.

Android Studio'yu açın ve Yeni bir Android Studio projesi başlat'ı tıklayın.

Android Studio, bir etkinlik türü seçmenizi ister. Güvenilir Web Etkinlikleri, destek kitaplığı tarafından sağlanan bir etkinlik kullandığından Etkinlik Ekle'yi seçin ve Sonraki'yi tıklayın.

Bir sonraki adımda sihirbaz, proje için yapılandırma isteğinde bulunur. Her alanın kısa bir açıklaması aşağıda verilmiştir:

• Ad: Android Launcher'da uygulamanız için kullanılacak ad.
• Paket Adı: Play Store'daki ve Android cihazlardaki Android uygulamaları için benzersiz bir tanımlayıcı. Android uygulamaları için paket adı oluşturmayla ilgili koşullar ve en iyi uygulamalar hakkında daha fazla bilgi için dokümanları inceleyin.
• Kaydetme konumu: Android Studio'nun projeyi dosya sisteminde oluşturacağı yer.
• Dil: Proje için Java veya Kotlin kodu yazmanız gerekmez. Varsayılan olarak Java'yı seçin.
• Minimum API Düzeyi: Destek Kitaplığı için en az API düzeyi 16 gerekir. API 16 veya sonraki bir sürümü seçin.

Hazır Uygulamalar veya AndroidX yapıları kullanmayacağımızdan kalan onay kutularının işaretini kaldırın ve Son'u tıklayın.

Güvenilir Web Etkinliği Destek Kitaplığı'nı edinme

Projede Güvenilir Web Etkinliği kitaplığını ayarlamak için uygulama derleme dosyasını düzenlemeniz gerekir. Proje Gezgini'nde Gradle Komut Dosyaları bölümünü bulun. build.gradle adlı iki dosya vardır. Bu durum biraz kafa karıştırıcı olabilir. Doğru dosyayı belirlemenize parantez içindeki açıklamalar yardımcı olur.

Aradığımız dosya, adının yanında modül Modül ifadesinin bulunduğu dosyadır.

Güvenilir Web Etkinlikleri kitaplığı Java 8 özelliklerini kullanır ve ilk değişiklik Java 8'i etkinleştirir. android bölümünün altına aşağıdaki gibi bir compileOptions bölümü ekleyin:

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

Sonraki adımda, Güvenilir Web Etkinliği Destek Kitaplığı projeye eklenir. dependencies bölümüne yeni bir bağımlılık ekleyin:

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

Android Studio, projeyi bir kez daha senkronize etmenizi isteyen bir istem gösterir. Şimdi Senkronize Et bağlantısını tıklayıp senkronize edin.

Güvenilir Web Etkinliği'ni başlatma

Güvenilir Web Etkinliği, Android Uygulama Manifesti düzenlenerek ayarlanır.

Proje Gezgini'nde uygulama bölümünü, ardından manifestler'i genişletin ve dosyayı açmak için AndroidManifest.xml simgesini çift tıklayın.

Android Studio'dan projemizi oluştururken projemize etkinlik eklememesini istediğimizden manifest boştur ve yalnızca uygulama etiketini içerir.

application etiketine bir activity etiketi ekleyerek Güvenilir Web Etkinliği'ni ekleyin:

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

XML'e eklenen etiketler standart Android Uygulama Manifesti'dir. Güvenilir Web Etkinlikleri bağlamıyla ilgili iki alakalı bilgi vardır:

1. meta-data etiketi, Güvenilir Web Etkinliği'ne hangi URL'yi açması gerektiğini söyler. android:value özelliğini, açmak istediğiniz PWA'nın URL'siyle değiştirin. Bu örnekte https://airhorner.com olarak ayarlanmıştır.
2. İkinci intent-filter etiketi, Güvenilir Web Etkinliği'nin https://airhorner.com'ı açan Android Intent'lerini durdurmasına olanak tanır. data etiketindeki android:host özelliği, Güvenilir Web Etkinliği tarafından açılan alanı işaret etmelidir.

Not: Proje bu aşamada çalıştırıldığında, Özel Sekmeler'deki URL çubuğu ekranın üst kısmında gösterilmeye devam eder. Bu bir hata değildir.

Bir sonraki bölümde, web sitesi ile uygulama arasındaki ilişkiyi doğrulamak ve URL çubuğunu kaldırmak için Digital AssetLinks'in nasıl ayarlanacağı gösterilmektedir.

URL çubuğunu kaldırma

Güvenilir Web Etkinlikleri, URL çubuğunun kaldırılması için Android uygulaması ile web sitesi arasında bir ilişkilendirme kurulmasını gerektirir.

Bu ilişkilendirme Digital Asset Links üzerinden oluşturulur ve uygulamadan web sitesine ve web sitesinden uygulamaya bağlantı oluşturarak her iki yönde de kurulmalıdır.

Hata ayıklama amacıyla uygulamayı web sitesi doğrulamasına, Chrome'u ise web sitesi doğrulamasını atlamaya ayarlayabilirsiniz.

Uygulama ile web sitesi arasında ilişkilendirme oluşturma

app > res > values > strings.xml dize kaynakları dosyasını açın ve aşağıdaki Digital AssetLinks ifadesini ekleyin:

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

site özelliğinin içeriğini, Güvenilir Web Etkinliği tarafından açılan şemaya ve alana uyacak şekilde değiştirin.

Android uygulama manifesti dosyasına geri dönün (AndroidManifest.xml). Bu kez application etiketinin alt öğesi olarak yeni bir meta-data etiketi ekleyerek ifadeye bağlantı verin:

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

Android uygulaması ile web sitesi arasında bir ilişki oluşturduk. Web sitesini uygulama doğrulamasına eklemeden ilişkinin bu kısmında hata ayıklama yapmak faydalıdır.

Bunu geliştirme cihazında test etmek için:

Hata ayıklama modunu etkinleştirme

1. Geliştirme cihazında Chrome'u açın, chrome://flags bölümüne gidin, Köklendirilmemiş cihazlarda komut satırını etkinleştir adlı öğeyi arayın ve ETKİN olarak değiştirin, ardından tarayıcıyı yeniden başlatın.
2. Ardından, işletim sisteminizin Terminal uygulamasında Android Hata Ayıklama Köprüsü'nü (Android Studio ile yüklenir) kullanın ve aşağıdaki komutu çalıştırın:

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

Chrome'u kapatın ve uygulamanızı Android Studio'dan yeniden başlatın. Uygulama artık tam ekranda gösterilecektir.

Not: Doğru komut satırıyla yeniden başlatılması için Chrome'u zorla kapatmanız gerekebilir. Android Ayarları > Uygulamalar ve bildirimler > Chrome'a gidin ve Zorla durdur'u tıklayın.

Web sitesinden uygulamaya ilişkilendirme oluşturma

Geliştiricinin ilişkilendirmeyi oluşturmak için uygulamadan toplaması gereken 2 bilgi vardır:

• Paket Adı: İlk bilgi, uygulamanın paket adıdır. Bu, uygulama oluşturulurken oluşturulan paket adıyla aynıdır. Modül build.gradle içinde, Gradle Komut Dosyaları > build.gradle (Modül: uygulama) altında da bulunabilir ve applicationId özelliğinin değeridir.
• SHA-256 parmak izi: Android uygulamaları Play Store'a yüklenebilmek için imzalanmış olmalıdır. Yükleme anahtarının SHA-256 parmak izi aracılığıyla web sitesi ile uygulama arasında bağlantı kurmak için de aynı imza kullanılır.

Android dokümanlarında Android Studio kullanılarak anahtar oluşturma işlemi ayrıntılı olarak açıklanmaktadır. Bir sonraki adımda ihtiyacınız olacağından anahtar deposunun yolunu, takma adını ve şifrelerini not edin.

Aşağıdaki komutu kullanarak keytool'u kullanarak SHA-256 parmak izini çıkarın:

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

SHA-256 parmak izi değeri, Sertifika parmak izi bölümünde yazdırılır. Aşağıda bir örnek çıkış verilmiştir:

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

Her iki bilgiyi de elinize aldıktan sonra assetlinks oluşturucuya gidin, alanları doldurun ve Açıklama Oluştur'u tıklayın. Oluşturulan ifadeyi kopyalayıp alanınızdan, /.well-known/assetlinks.json URL'sinden yayınlayın.

Not: AssetLinks dosyası, Chrome'un yalnızca bu yeri aradığından /.well-known/assetlinks.json altında, alanın kökünde olmalıdır.

Simge oluşturma

Android Studio yeni bir proje oluşturduğunda varsayılan bir simgeyle gelir. Geliştirici olarak kendi simgenizi oluşturmak ve uygulamanızı Android Launcher'daki diğer uygulamalardan ayırt etmek istersiniz.

Android Studio, her çözünürlük için doğru simgeleri oluşturmak ve uygulama ihtiyaçlarınızı şekillendirmek için gerekli araçları sağlayan Image Asset Studio'yu içerir.

Android Studio'da File > New > Image Asset bölümüne gidin, Launcher Icons (Adaptative and Legacy)'ü seçin ve uygulama için özel bir simge oluşturmak üzere sihirbazdaki adımları uygulayın.

İmzalı APK oluşturma

Alanınızda assetlinks dosyası ve Android uygulamasında asset_statements etiketi yapılandırıldıktan sonra, bir sonraki adım imzalanmış bir uygulama oluşturmaktır. Bu adımlarla ilgili bilgiler yaygın olarak mevcuttur.

Çıkış APK'sı, adb kullanılarak bir test cihazına yüklenebilir:

adb install app-release.apk

Doğrulama adımı başarısız olursa Android Hata Ayıklama Köprüsü'nü kullanarak, işletim sisteminizin terminalinden ve test cihazı bağlıyken hata mesajlarını kontrol edebilirsiniz.

adb logcat | grep -e OriginVerifier -e digital_asset_links

Oluşturulan yükleme APK'sı ile artık uygulamayı Play Store'a yükleyebilirsiniz.

Başlangıç ekranı ekleme

Chrome 75'ten itibaren Güvenilir Web Etkinlikleri, başlangıç ekranlarını destekler. Projeye birkaç yeni resim dosyası ve yapılandırma ekleyerek açılış ekranı ayarlanabilir.

Chrome 75 veya sonraki bir sürüme güncellediğinizden ve Güvenilir Web Etkinliği Destek Kitaplığı'nın en son sürümünü kullandığınızdan emin olun.

Başlangıç ekranı resimlerini oluşturma

Android cihazların ekran boyutları ve piksel yoğunlukları farklı olabilir. Başlangıç ekranının tüm cihazlarda iyi görünmesini sağlamak için her piksel yoğunluğu için resmi oluşturmanız gerekir.

Ekrandan bağımsız piksellerin (dp veya dip) tam açıklaması bu makalenin kapsamı dışındadır. Ancak 320x320 dp boyutunda bir resim oluşturmak, herhangi bir yoğunluktaki cihaz ekranında 2x2 inçlik bir kareyi temsil eden ve mdpi yoğunluğunda 320x320 piksele eşdeğer olan bir örnektir.

Buradan diğer piksel yoğunlukları için gereken boyutları belirleyebiliriz. Aşağıda, piksel yoğunlukları, temel boyuta (320x320 dp) uygulanan çarpan, piksel cinsinden elde edilen boyut ve resmin Android Studio projesine eklenmesi gereken konumun yer aldığı bir liste verilmiştir.

Yoğunluk	Çarpan	Boyut	Proje Konumu
mdpi (referans değer)	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/

Not: Tüm resim boyutlarını oluşturmanın alternatifi, bir vektor çizilebilir öğesi kullanmaktır. Vector Asset Studio, geliştiricilerin SVG'leri Android vektör çizimlerine dönüştürmesine yardımcı olacak araçlar sunar.

Uygulamayı güncelleme

Açılış ekranı resimleri oluşturulduktan sonra projeye gerekli yapılandırmaları ekleme zamanı gelmiştir.

Öncelikle Android manifest dosyasına (AndroidManifest.xml) bir content-provider ekleyin.

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

Not: Bir cihazda iki uygulamanın aynı yetkiye sahip olamayacağından, sağlayıcıyı oluştururken android:authorities özelliğini değiştirmeyi unutmayın.

Ardından, res/xml/filepaths.xml kaynağını ekleyin ve TWA açılış ekranının yolunu belirtin:

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

Son olarak, LauncherActivity'yi özelleştirmek için Android Manifest dosyasına meta-tags ekleyin:

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

android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY etiketinin değerinin, provider etiketi içindeki android:authorities özelliği için tanımlanan değerle eşleştiğinden emin olun.

LauncherActivity'yi şeffaf hale getirme

Ayrıca, LauncherActivity için yarı saydam bir tema ayarlayarak açılış ekranından önce beyaz ekran gösterilmesini önlemek amacıyla LauncherActivity'nin şeffaf olduğundan emin olun:

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

Geliştiricilerin Güvenilir Web Etkinlikleri ile neler oluşturacağını görmek için sabırsızlanıyoruz. Geri bildirimde bulunmak için @ChromiumDev adresinden bize ulaşabilirsiniz.