דף זה תורגם על ידי Cloud Translation API.

מדריך לשילוב

André Cipriani Bandarra

כדי להגדיר פעילות באינטרנט מהימנה, המפתחים לא צריכים לכתוב קוד Java, אבל נדרש Android Studio. המדריך הזה נוצר באמצעות Android Studio 3.3. כאן מוסבר איך להתקין את הספרייה.

יצירת פרויקט של Trusted Web Activity

כשמשתמשים ב-Trusted Web Activities, הפרויקט חייב לטרגט ל-API 16 ואילך.

פותחים את Android Studio ולוחצים על Start a new Android Studio project (התחלת פרויקט חדש ב-Android Studio).

ב-Android Studio תופיע בקשה לבחור סוג פעילות. מכיוון שפעילויות מהימנות באינטרנט משתמשות בפעילות שסופקה על ידי ספריית התמיכה, בוחרים באפשרות Add No Activity ולוחצים על Next.

בשלב הבא, האשף יבקש להגדיר את הפרויקט. הנה תיאור קצר של כל שדה:

שם: השם שישמש את האפליקציה ב-Android Launcher.
שם החבילה: מזהה ייחודי של אפליקציות ל-Android בחנות Play ובמכשירי Android. בתיעוד מפורט מידע נוסף על הדרישות והשיטות המומלצות ליצירת שמות חבילות לאפליקציות ל-Android.
מיקום השמירה: המקום שבו Android Studio תיצור את הפרויקט במערכת הקבצים.
שפה: הפרויקט לא מצריך כתיבת קוד Java או Kotlin. בוחרים ב-Java כברירת מחדל.
רמת API מינימלית: כדי להשתמש בספריית התמיכה נדרשת לפחות רמת API 16. בוחרים ב-API 16 וכל גרסה ואילך.

משאירים את התיבות הנותרות לא מסומנות, כי לא נשתמש באפליקציות ללא התקנה או ב-artifacts של AndroidX, ולוחצים על Finish.

הורדת ספריית התמיכה של Trusted Web Activity

כדי להגדיר את הספרייה Trusted Web Activity בפרויקט, צריך לערוך את קובץ ה-build של האפליקציה. מחפשים את הקטע Gradle Scripts בProject Navigator. יש שני קבצים שנקראים build.gradle, ויכול להיות שזה קצת מבלבל. התיאורים בסוגריים עוזרים לזהות את הקובץ הנכון.

הקובץ שאנחנו מחפשים הוא זה עם המודול Module לצד השם שלו.

בספריית Trusted Web Activities נעשה שימוש בתכונות של Java 8, והשינוי הראשון מאפשר את השימוש ב-Java 8. מוסיפים קטע compileOptions לתחתית הקטע android, כפי שמתואר בהמשך:

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

בשלב הבא נוסיף לפרויקט את ספריית התמיכה בפעילות מהימנה באינטרנט. מוסיפים יחסי תלות חדשים לקטע dependencies:

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

ב-Android Studio תוצג בקשה לסנכרן את הפרויקט שוב. לוחצים על הקישור סנכרון עכשיו ומבצעים סנכרון.

הפעלת הפעילות Trusted Web

כדי להגדיר את הפעילות המאומתת באינטרנט, עורכים את Android App Manifest.

ב-Project Navigator, מרחיבים את הקטע app ואז את הקטע manifests ולוחצים לחיצה כפולה על AndroidManifest.xml כדי לפתוח את הקובץ.

מכיוון שביקשנו מ-Android Studio לא להוסיף אף פעילות לפרויקט שלנו בזמן יצירתו, המניפסט ריק ומכיל רק את תג האפליקציה.

כדי להוסיף את פעילות האינטרנט המהימנה, מוסיפים תג activity לתג 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>

התגים שנוספו לקובץ ה-XML הם Android App Manifest רגילים. יש שני פרטי מידע רלוונטיים להקשר של 'פעילויות אינטרנט מהימנות':

התג meta-data מציין ל-Trusted Web Activity איזו כתובת URL צריך לפתוח. משנים את המאפיין android:value בכתובת ה-URL של ה-PWA שרוצים לפתוח. בדוגמה הזו, זהו https://airhorner.com.
התג השני intent-filter מאפשר לפעילות המהימנה באינטרנט ליירט אובייקטים של Intent של Android שפותחים את https://airhorner.com. המאפיין android:host בתוך התג data חייב להפנות לדומיין שנפתח על ידי Trusted Web Activity.

בקטע הבא נסביר איך להגדיר Digital Asset Links כדי לאמת את הקשר בין האתר לאפליקציה ולהסיר את סרגל כתובות ה-URL.

הסרת סרגל כתובות ה-URL

כדי להסיר את סרגל כתובות ה-URL, צריך ליצור שיוך בין אפליקציית Android לבין האתר בפעילות באינטרנט מהימנה.

השיוך הזה נוצר באמצעות Digital Asset Links, וצריך ליצור אותו בשני הכיוונים: קישור מהאפליקציה לאתר וקישור מהאתר לאפליקציה.

אפשר להגדיר את האפליקציה לאימות אתר ולהגדיר את Chrome לדלג על האימות באתר ולעבור לאימות האפליקציה, למטרות ניפוי באגים.

יצירת שיוך מהאפליקציה לאתר

פותחים את קובץ משאבי המחרוזת app > res > values > strings.xml ומוסיפים את ההצהרה 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>

משנים את התוכן של המאפיין site כך שיתאים לסכימה ולדומיין שנפתחים על ידי Trusted Web Activity.

בחזרה בקובץ המניפסט של האפליקציה ל-Android, AndroidManifest.xml, מוסיפים קישור לדף החשבון באמצעות הוספת תג meta-data חדש, אבל הפעם כצאצא של התג 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>

עכשיו יצרנו קשר בין האפליקציה ל-Android לאתר. כדאי לנפות באגים בחלק הזה של הקשר בלי ליצור את האתר לאימות של האפליקציה.

כך בודקים את זה במכשיר פיתוח:

הפעלה של מצב ניפוי באגים

פותחים את Chrome במכשיר הפיתוח, עוברים אל chrome://flags, מחפשים פריט בשם הפעלת שורת הפקודה במכשירים ללא הרשאות בסיס, משנים אותו למופעל ומפעילים מחדש את הדפדפן.
לאחר מכן, באפליקציית הטרמינל של מערכת ההפעלה, משתמשים ב-Android Debug Bridge (שמתקינים עם Android Studio) ומריצים את הפקודה הבאה:

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

סוגרים את Chrome ופותחים מחדש את האפליקציה מ-Android Studio. האפליקציה אמורה להופיע במסך מלא.

יצירת שיוך בין האתר לאפליקציה

כדי ליצור את השיוך, המפתח צריך לאסוף מהאפליקציה שני פרטי מידע:

שם החבילה: המידע הראשון הוא שם החבילה של האפליקציה. זהו אותו שם חבילה שנוצר כשיצרתם את האפליקציה. אפשר למצוא אותו גם במודול build.gradle, בקטע Gradle Scripts‏ > build.gradle (Module: app), והוא הערך של המאפיין applicationId.
טביעת אצבע SHA-256: כדי להעלות אפליקציות ל-Android לחנות Play, עליהן להיות חתומות. אותה חתימה משמשת ליצירת החיבור בין האתר לאפליקציה באמצעות טביעת האצבע SHA-256 של מפתח ההעלאה.

במסמכי העזרה של Android מוסבר בפירוט איך ליצור מפתח באמצעות Android Studio. הקפידו לרשום את הנתיב, הכינויים והסיסמאות של מאגר המפתחות, כי תצטרכו אותם בשלב הבא.

מחלצים את טביעת האצבע מסוג SHA-256 באמצעות keytool, באמצעות הפקודה הבאה:

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

הערך של טביעת האצבע מסוג SHA-256 מודפס בקטע טביעות אצבע של אישורים. דוגמה לפלט:

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

אחרי שמקבלים את שני קטעי המידע, עוברים אל הכלי ליצירת קישורי asset, ממלאים את השדות ולוחצים על Generate Statement (יצירת הצהרה). מעתיקים את ההצהרה שנוצרה ושולחים אותה מהדומיין שלכם, מכתובת ה-URL /.well-known/assetlinks.json.

יצירת סמל

כשאתם יוצרים פרויקט חדש ב-Android Studio, הוא מגיע עם סמל ברירת מחדל. כמפתחים, כדאי ליצור סמל משלכם כדי להבדיל את האפליקציה שלכם מאחרות במרכז האפליקציות של Android.

ב-Android Studio תמצאו את Image Asset Studio, שמספק את הכלים הדרושים ליצירת הסמלים הנכונים, לכל רזולוציה ולעיצוב של האפליקציה שלכם.

ב-Android Studio, עוברים אל File > New > Image Asset, בוחרים באפשרות Launcher Icons (Adaptative and Legacy) ופועלים לפי השלבים במדריך כדי ליצור סמל מותאם אישית לאפליקציה.

יצירת קובץ APK חתום

אחרי שהקובץ assetlinks כבר קיים בדומיין והתג asset_statements מוגדר באפליקציה ל-Android, השלב הבא הוא יצירת אפליקציה חתומה. שוב, השלבים הרלוונטיים בדרך הזו מתועדים באופן נרחב.

אפשר להתקין את קובץ ה-APK של הפלט במכשיר בדיקה באמצעות adb:

adb install app-release.apk

אם שלב האימות נכשל, אפשר לבדוק אם יש הודעות שגיאה באמצעות ה-Android Debug Bridge, הטרמינל של מערכת ההפעלה ומכשיר הבדיקה מחובר.

adb logcat | grep -e OriginVerifier -e digital_asset_links

עכשיו, אחרי שיצרתם את קובץ ה-APK להעלאה, אתם יכולים להעלות את האפליקציה לחנות Play.

הוספת מסך פתיחה

החל מ-Chrome 75, תהיה תמיכה במסכי פתיחה במסגרת 'פעילויות מהימנות באינטרנט'. כדי להגדיר את מסך הפתיחה, אפשר להוסיף לפרויקט מספר קובצי תמונות חדשים והגדרות אישיות.

חשוב לעדכן את הדפדפן ל-Chrome 75 ואילך ולהשתמש בגרסה האחרונה של Trusted Web Activity Support Library.

יצירת התמונות של מסך הפתיחה

למכשירי Android יכולים להיות גדלי מסך ודחיסות פיקסלים שונים. כדי להבטיח שתמונת הרקע תיראה טוב בכל המכשירים, תצטרכו ליצור את התמונה לכל צפיפות פיקסלים.

הסבר מלא על פיקסלים שאינם תלויים במסך (dp או dip) חורג מהיקף המאמר הזה, אבל דוגמה אחת היא יצירת תמונה בגודל 320x320dp, שמייצגת ריבוע בגודל 2x2 אינץ' במסך של מכשיר בכל צפיפות, ושווה ערך ל-320x320 פיקסלים בצפיפות mdpi.

משם נוכל להסיק את הגדלים הדרושים לדחיסות פיקסלים אחרת. בהמשך מופיעה רשימה עם דחיסות הפיקסלים, המכפיל שמוחל על הגודל הבסיסי (320x320dp), הגודל שמתקבל בפיקסלים והמיקום שבו צריך להוסיף את התמונה בפרויקט Android Studio.

צפיפות	מכפיל	גודל	מיקום הפרויקט
mdpi (baseline)	1.0x	320x320 פיקסלים	/res/drawable-mdpi/
ldpi	0.75x	240x240 פיקסלים	/res/drawable-ldpi/
hdpi	1.5x	480x480 פיקסלים	/res/drawable-hdpi/
xhdpi	2.0x	640x640 פיקסלים	/res/drawable-xhdpi/
xxhdpi	3.0x	960x960 פיקסלים	/res/drawable-xxhdpi/
xxxhdpi	4.0x	1280x1280 פיקסלים	/res/drawable-xxxhdpi/

מתבצע עדכון של האפליקציה

אחרי שיצרתם את התמונות של מסך הפתיחה, הגיע הזמן להוסיף את ההגדרות הנדרשות לפרויקט.

קודם מוסיפים content-provider למניפסט של 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>

לאחר מכן, מוסיפים את המשאב res/xml/filepaths.xml ומציינים את הנתיב למסך הפתיחה של Twa:

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

לסיום, מוסיפים את meta-tags ל-Android Manifest כדי להתאים אישית את 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>

חשוב לוודא שהערך של התג android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY תואם לערך המוגדר של המאפיין android:authorities בתוך התג provider.

הפיכת LauncherActivity לשקופה

בנוסף, מוודאים שהפעילות של LauncherActivity שקופה כדי למנוע הצגה של מסך לבן לפני הפתיחה:

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

אנחנו מחכים לראות מה המפתחים ייצרו באמצעות Trusted Web Activities. כדי לשלוח משוב, אפשר לפנות אלינו ב-‎@ChromiumDev.