מדריך לשילוב

André Cipriani Bandarra

הערה: הערה: מדריך למתחילים בנושא פעילויות מהימנות באינטרנט זמינה עכשיו.

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

יצירת פרויקט של פעילות מהימנה באינטרנט

כשמשתמשים בפעילויות מהימנות באינטרנט, הפרויקט חייב לטרגט ל-API בגרסה 16 ואילך.

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

פותחים את Android Studio ולוחצים על התחלה של פרויקט חדש של Android Studio.

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

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

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

צריך להשאיר את תיבות הסימון הנותרות לא מסומנות, כי לא נשתמש באפליקציות ללא התקנה. או פריטי מידע שנוצרו בתהליך פיתוח (Artifact) של AndroidX, ולוחצים על Finish.

ספריית התמיכה הנדרשת לפעילות באינטרנט

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

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

ספריית הפעילויות המהימנות באינטרנט משתמשת תכונות 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 תוצג בקשה לסנכרן את הפרויקט פעם נוספת. לוחצים על הקישור Sync Now (סנכרון עכשיו) ומסנכרנים אותו.

הפעלת 'פעילות מהימנה באינטרנט'

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

ב-Project Navigator, מרחיבים את הקטע app ואז את הקטע מניפסטים ולוחצים לחיצה כפולה על 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. יש שני פרטים רלוונטיים בהקשר של 'אינטרנט מהימן' פעילויות:

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

הערה: כשמפעילים את הפרויקט בשלב הזה, סרגל כתובות ה-URL מכרטיסיות מותאמות אישית עדיין יופיעו בחלק העליון של המסך. זה לא באג.

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

צריך להסיר את סרגל כתובות ה-URL

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

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

אפשר להגדיר את האפליקציה לאימות האתר ולהגדיר את 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 כך שיתאים לסכימה ולדומיין נפתח על ידי 'פעילות מהימנה באינטרנט'.

בחזרה בקובץ המניפסט של האפליקציה ל-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 האתר. כדאי לנפות באגים בחלק הזה של הקשר בלי ליצור מהאתר לאימות של אפליקציה.

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

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

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

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

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

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

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

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

• שם החבילה: המידע הראשון הוא שם החבילה של האפליקציה. הזה הוא אותו שם חבילה שנוצר במהלך יצירת האפליקציה. אפשר למצוא אותו גם בתוך המודול build.gradle, סקריפטים של Gradle > build.gradle (מודול: אפליקציה), וזהו הערך של 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

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

הערה: הקובץ AssetLinks חייב להיות מתחת ל-/.well-known/assetlinks.json, ב הבסיסי (root) של הדומיין, כי זה רק המקום שבו Chrome יחפש אותו.

יצירת סמל

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

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 ואילך ולהשתמש הגרסה העדכנית של ספריית התמיכה המהימנה בפעילות באינטרנט.

המערכת יוצרת את התמונות למסך הפתיחה

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

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

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

צפיפות	מכפיל	גודל	מיקום הפרויקט
mdpi (ערך הבסיס)	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.0	960x960 פיקסלים	/res/drawable-xxhdpi/
xxxhdpi	4.0x	1280x1280 פיקסלים	/res/drawable-xxxhdpi/

הערה: במקום ליצור כל תמונה אפשר להשתמש בטיוטה וקטורית בלבד. Vector Asset Studio מציע כלים שיעזרו למפתחים להפוך קובצי SVG ל-Android Vector Drawables.

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

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

קודם כול, מוסיפים 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>

הערה: חשוב לשנות את המאפיין android:authorities כשיוצרים את הספק. כי לשתי אפליקציות לא יכולה להיות אותה הרשאה במכשיר.

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

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

לסיום, מוסיפים את meta-tags למניפסט של Android כדי להתאים אישית את פעילות מרכז האפליקציות:

<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 שקוף כדי להימנע ממסך לבן שמוצגת לפני הפתיחה על ידי הגדרת עיצוב שקוף לפעילות במרכז האפליקציות:

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

נשמח לראות מה מפתחים יוכלו לפתח באמצעות 'אינטרנט מהימן' פעילויות. כדי לשלוח משוב, אפשר ליצור איתנו קשר בכתובת @ChromiumDev.