دليل الدمج

أندريه سيبرياني باندارا
"أندريه سيبرياني باندارا"
Twitter GitHub تأثير اهتزاز Mastodon الصفحة الرئيسية

لا يشترط إعداد "نشاط ويب موثوق به" على المطوّرين إنشاء رمز Java، ولكن استوديو Android مطلوب. تم إنشاء هذا الدليل باستخدام الإصدار 3.3 من استوديو Android. راجِع المستندات المتعلقة بكيفية تثبيته.

إنشاء مشروع نشاط ويب موثوق به

عند استخدام أنشطة الويب الموثوقة، يجب أن يستهدف المشروع واجهة برمجة التطبيقات 16 أو الإصدارات الأعلى.

افتح "استوديو Android" وانقر على بدء مشروع جديد على "استوديو Android".

سيطلب تطبيق "استوديو Android" اختيار نوع النشاط. نظرًا لأن أنشطة الويب الموثوق بها تستخدم نشاطًا تقدمه مكتبة الدعم، اختر إضافة ما من نشاط وانقر على التالي.

الخطوة التالية، سيطالب المعالج بإجراء عمليات ضبط للمشروع. إليك وصف موجز لكل حقل:

  • الاسم: الاسم الذي سيتم استخدامه لتطبيقك على Android Launcher.
  • اسم الحزمة: معرّف فريد لتطبيقات Android على "متجر Play" وعلى أجهزة Android. راجع المستندات لمزيد من المعلومات حول المتطلبات وأفضل الممارسات لإنشاء أسماء الحزم لتطبيقات Android.
  • حفظ الموقع: المكان الذي سينشئ فيه Android Studio المشروع في نظام الملفات.
  • اللغة: لا يتطلّب المشروع كتابة أيّ رمز Java أو Kotlin. حدد Java، كإعداد افتراضي.
  • الحد الأدنى لمستوى واجهة برمجة التطبيقات: تتطلّب "مكتبة الدعم" المستوى 16 لواجهة برمجة التطبيقات على الأقل. اختَر API 16 بأي إصدار أعلاه.

اترك مربعات الاختيار المتبقية بدون تحديد، لأننا لن نستخدم التطبيقات الفورية أو عناصر AndroidX، وانقر على إنهاء.

الحصول على مكتبة دعم الأنشطة على الويب الموثوق بها

لإعداد مكتبة النشاط على الويب الموثوق بها في المشروع، ستحتاج إلى تعديل ملف إنشاء التطبيق. ابحث عن قسم Gradle Scripts في Project Navigator (أداة تصفح المشروع). هناك ملفان باسم build.gradle قد يكونان مربكين بعض الشيء وتساعد الأوصاف الواردة بين قوسين في تحديد الملف الصحيح.

والملف الذي نبحث عنه هو الملف الذي يحتوي على الوحدة Module بجانب اسمه.

تستخدم مكتبة الأنشطة على الويب الموثوق بها ميزات 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 رسالة تطلب منك مزامنة المشروع مرة أخرى. انقر على الرابط مزامنة الآن وقم بمزامنته.

تشغيل نشاط الويب الموثوق به

يتم إعداد "النشاط على الويب الموثوق به" من خلال تعديل بيان تطبيق Android.

في Project Navigator (أداة تصفُّح المشروع)، وسِّع قسم app، متبوعًا بالبيانات، ثم انقر مرّتين على AndroidManifest.xml لفتح الملف.

بما أنّنا طلبنا من "استوديو Android" عدم إضافة أي "نشاط" إلى مشروعنا عند إنشائه، فإن البيان فارغ ويتضمن علامة التطبيق فقط.

أضِف نشاط الويب الموثوق به من خلال إدراج علامة 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 التي تفتح https://airhorner.com. يجب أن تشير السمة android:host داخل العلامة data إلى النطاق الذي يفتحه "نشاط الويب الموثوق به".

سيوضح القسم التالي كيفية إعداد Digital AssetLinks للتحقق من العلاقة بين الموقع الإلكتروني والتطبيق، وإزالة شريط عنوان URL.

إزالة شريط عنوان URL

تتطلب أنشطة الويب الموثوق بها إنشاء رابط بين تطبيق Android وموقع الويب لإزالة شريط عنوان URL.

يتم إنشاء عملية الربط هذه من خلال ميزة 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 ليتطابق مع المخطط والنطاق في صفحة "النشاط على الويب الموثوق به".

في ملف بيان تطبيق 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، وابحث عن عنصر باسم تفعيل سطر الأوامر على الأجهزة غير المزوّدة بإذن الوصول إلى الجذر وغيِّره إلى تفعيل، ثم أعِد تشغيل المتصفِّح.
  2. بعد ذلك، في تطبيق Terminal في نظام التشغيل، استخدِم Android Debug Bridge (المثبَّت من خلال "استوديو Android") وشغِّل الأمر التالي:
adb shell "echo '_ --disable-digital-asset-link-verification-for-url=\"https://airhorner.com\"' > /data/local/tmp/chrome-command-line"

أغلِق Chrome وأعِد تشغيل تطبيقك من "استوديو Android". من المفترض أن يظهر التطبيق الآن في وضع ملء الشاشة.

هناك جزآن من المعلومات يحتاج مطوِّر البرامج إلى جمعها من التطبيق لإنشاء عملية الربط:

  • اسم الحزمة: المعلومات الأولى هي اسم الحزمة للتطبيق. هذا هو اسم الحزمة نفسه الذي تم إنشاؤه عند إنشاء التطبيق. ويمكن العثور عليه أيضًا داخل Module build.gradle، ضمن Gradle Scripts > Build.gradele (Module: app)، وهي قيمة السمة applicationId.
  • بصمة إصبع SHA-256: يجب تسجيل تطبيقات Android لتحميلها إلى "متجر Play". ويُستخدم التوقيع نفسه لإنشاء اتصال بين الموقع الإلكتروني والتطبيق من خلال الملف المرجعي SHA-256 لمفتاح التحميل.

تشرح مستندات Android كيفية إنشاء مفتاح باستخدام "استوديو Android" بالتفصيل. احرِص على تدوين المسار والعنوان البديل للبريد الإلكتروني وكلمات المرور لملف تخزين المفاتيح لأنّك ستحتاج إليه في الخطوة التالية.

استخرِج الملف المرجعي لخوارزمية 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

بعد الاطّلاع على المعلومات المطلوبة، يمكنك الانتقال إلى أداة إنشاء روابط مواد العرض، وملء الحقول والنقر على إنشاء بيان. انسخ العبارة التي تم إنشاؤها واعرضها من نطاقك، من عنوان URL /.well-known/assetlinks.json.

إنشاء رمز

عندما ينشئ "استوديو Android" مشروعًا جديدًا، سيظهر له رمز تلقائي. بصفتك مطورًا، ستحتاج إلى إنشاء رمزك الخاص وتمييز تطبيقك عن التطبيقات الأخرى المتوفرة على Android Launcher.

يحتوي "استوديو Android" على Image Asset Studio الذي يوفّر الأدوات اللازمة لإنشاء الرموز الصحيحة لكل درجة دقة وتشكيل يحتاجها تطبيقك.

ضمن "استوديو Android"، انتقِل إلى 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، تتوافق أنشطة الويب الموثوق بها مع شاشات البداية. يمكن إعداد شاشة البداية من خلال إضافة بعض ملفات الصور والإعدادات الجديدة إلى المشروع.

تأكَّد من التحديث إلى الإصدار 75 من Chrome أو إصدار أحدث واستخدام أحدث إصدار من مكتبة دعم النشاط على الويب الموثوق به.

إنشاء صور لشاشة البداية

يمكن أن يكون لأجهزة Android أحجام شاشات وكثافات بكسل مختلفة. لضمان ظهور شاشة البداية بشكل جيد على جميع الأجهزة، ستحتاج إلى إنشاء صورة لكل كثافة بكسل.

الشرح الكامل لوحدات البكسل غير المرتبطة بشاشة العرض (dp أو dip) يتجاوز نطاق هذه المقالة، ومن الأمثلة على ذلك إنشاء صورة بحجم 320x320dp، والتي تمثل مربّعًا بحجم 2×2 بوصة على شاشة جهاز بأي كثافة وتكافئ 320x320 بكسل بكثافة mdpi.

ومن هناك يمكننا استنتاج الأحجام المطلوبة لكثافات وحدات البكسل الأخرى. وفي ما يلي قائمة بكثافات وحدات بكسل، والمُضاعِف المطبّق على الحجم الأساسي (320×320 بكسل مستقل الكثافة)، والحجم الناتج بالبكسل، والموقع الجغرافي الذي يجب إضافة الصورة إليه في مشروع "استوديو Android".

الكثافة المُضاعِف حجم الملف موقع المشروع
mdpi (الخط القاعدي) 1.0x 320 × 320 بكسل /res/drawable-mdpi/
دبي 0.75x 240 × 240 بكسل /res/drawable-ldpi/
دقة hdpi 1.5x 480 × 480 بكسل /res/drawable-hdpi/
xhdpi 2.0x 640 × 640 بكسل /res/drawable-xhdpi/
xxhdpi 3 أضعاف 960 × 960 بكسل /res/drawable-xxhdpi/
xxxhdpi 4.0 أضعاف 1280 × 1280 بكسل /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 لتخصيص 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>

ونتطلع إلى معرفة ما يصممه المطورون باستخدام أنشطة الويب الموثوق بها. ولإيقاف أي ملاحظات، يمكنك التواصل معنا على @ChromiumDev.