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

מדריך לשילוב

אנדרה צ'יפריאני בנדרה

Twitter GitHub Glitch Mastodon דף הבית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Package Name: המידע הראשון הוא שם החבילה של האפליקציה. זהו שם החבילה שנוצר בזמן יצירת האפליקציה. ניתן למצוא אותו גם במודול 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

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

יצירת סמל

כשנוצר פרויקט חדש ב-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 (baseline)	1.0x	320x320 פיקסלים	/res/drawable-mdpi/
LDAP	0.75x	240x240 פיקסלים	/res/drawable-ldpi/
Hdpi	פי 1.5	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/

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

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

קודם כול, מוסיפים ספק תוכן למניפסט של 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 כדי להתאים אישית את הפעילות של מרכז האפליקציות:

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

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