تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

دليل الدمج

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 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 (أداة التنقّل في المشروع)، وسِّع قسم التطبيق، متبوعًا بملفات البيانات وانقر مرّتين على 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 عادية. هناك نوعان من المعلومات ذات الصلة بسياق أنشطة الويب الموثوق بها:

تُخبر علامة meta-data ميزة "النشاط الموثوق به على الويب" بعنوان URL الذي يجب فتحه. غيِّر سمة android:value باستخدام عنوان URL لتطبيق الويب التقدّمي الذي تريد فتحه. في هذا المثال، القيمة هي https://airhorner.com.
تسمح علامة 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 بموقع الويب. من المفيد تصحيح أخطاء هذا الجزء من العلاقة بدون إنشاء عملية التحقّق من الموقع الإلكتروني إلى التطبيق.

وإليك كيفية اختبار ذلك على جهاز تطوير:

تفعيل وضع تصحيح الأخطاء

افتح Chrome على جهاز التطوير، وانتقِل إلى chrome://flags، وابحث عن عنصر باسم تفعيل سطر الأوامر على الأجهزة غير المزوّدة بإذن الوصول إلى الجذر وغيِّره إلى مفعَّل، ثم أعِد تشغيل المتصفّح.
بعد ذلك، في تطبيق 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". يجب أن يظهر التطبيق الآن في وضع ملء الشاشة.

إنشاء ربط من الموقع الإلكتروني بالتطبيق

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

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