دليل الدمج

André Cipriani Bandarra

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

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

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

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

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

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

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

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

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

لإعداد مكتبة "نشاط الويب الموثوق به" في المشروع، عليك تعديل ملف Application build. ابحث عن قسم نصوص Gradle البرمجية في مستكشف المشاريع. هناك ملفان باسم 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 (التطبيق)، ثم 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 عادية. هناك معلومتان ذات صلة بسياق "أنشطة الويب الموثوق بها":

  1. تُخبر علامة meta-data ميزة "النشاط الموثوق به على الويب" بعنوان URL الذي يجب فتحه. غيِّر سمة android:value باستخدام عنوان URL لتطبيق الويب التقدّمي الذي تريد فتحه. في هذا المثال، هو https://airhorner.com.
  2. تسمح علامة intent-filter الثانية لميزة "النشاط الموثوق به على الويب" باعتراض طلبات Android Intent التي تفتح https://airhorner.com. يجب أن تشير سمة android:host داخل علامة data إلى النطاق الذي يفتحه "النشاط الموثوق به على الويب".

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

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

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

يتم إنشاء هذا الربط من خلال روابط مواد العرض الرقمية ويجب إجراء الربط بالطريقتين، أي الربط من التطبيق إلى الموقع الإلكتروني ومن الموقع الإلكتروني إلى التطبيق.

من الممكن إعداد التطبيق للتحقّق من الموقع الإلكتروني وإعداد Chrome لتخطّي التحقّق من الموقع الإلكتروني إلى التطبيق، وذلك لأغراض تصحيح الأخطاء.

افتح ملف موارد السلاسل app > res > values > strings.xml وأضِف statement 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 Studio. يجب أن يظهر التطبيق الآن في وضع ملء الشاشة.

هناك معلومتان يجب أن يجمعهما المطوّر من التطبيق لإنشاء عملية الربط:

  • اسم الحزمة: المعلومات الأولى هي اسم حزمة التطبيق. وهو اسم الحزمة نفسه الذي تم إنشاؤه عند إنشاء التطبيق. ويمكن العثور عليه أيضًا داخل وحدة build.gradle، ضمن نصوص Gradle البرمجية > build.gradle (الوحدة: تطبيق)، وهو قيمة سمة 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

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

إنشاء رمز

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

يحتوي "استوديو 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".

إضافة شاشة بداية

بدءًا من الإصدار 75 من Chrome، تتوفّر ميزة "شاشات البداية" في ميزة "أنشطة الويب الموثوق بها". يمكن إعداد شاشة البداية من خلال إضافة بعض ملفات الصور والإعدادات الجديدة إلى المشروع.

احرص على استخدام الإصدار 75 من Chrome أو إصدار أحدث وأحدث إصدار من مكتبة دعم Trusted Web Activity.

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

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

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

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

الكثافة المُضاعِف الحجم الموقع الجغرافي للمشروع
mdpi (المستوى الأساسي) 1.0x ‫320×320 بكسل /res/drawable-mdpi/
ldpi 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.0x ‫960 × 960 بكسل /res/drawable-xxhdpi/
xxxhdpi ‫4.0x ‫1280×1280 بكسل /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 وحدِّد المسار إلى شاشة البداية في تطبيقك المتوافق مع الأجهزة الجوّالة:

<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 شفاف لتجنُّب ظهور شاشة بيضاء قبل شاشة البداية من خلال ضبط مظهر شفاف لنشاط LauncherActivity:

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

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