تمت ترجمة هذه الصفحة بواسطة 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، وانقر على إنهاء.

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

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

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

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

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

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

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

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

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

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

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

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

إنشاء رمز

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

يحتوي Android Studio على 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 أو إصدار أحدث واستخدم أحدث إصدار من مكتبة دعم أنشطة الويب الموثوقة.

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

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

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

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

الكثافة	المُضاعِف	حجم الملف	الموقع الجغرافي للمشروع
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 مرات	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 شفافًا لتجنُّب ظهور شاشة بيضاء. قبل الظهور الأول من خلال ضبط مظهر شبه شفاف لـ LauncherActivity:

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

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