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

هل تم تثبيت تطبيقك؟ ستخبرك واجهة برمجة التطبيقات Get Installed Related Apps API بذلك.

Pete LePage

Alexey Rodionov

تتيح Get Installed Related Apps API الحصول على قائمة بالتطبيقات ذات الصلة المثبَّتة بالإضافة إلى تفاصيل عنها.

تتيح لك هذه الميزة التحقّق مما إذا كان تطبيق الويب التقدّمي أو تطبيق Android أو تطبيق Universal Windows Platform (UWP) مثبّتًا على الجهاز الحالي، وذلك من تطبيق الويب التقدّمي نفسه ومن صفحة ويب ذات صلة (مثل موقع إلكتروني لتسويق المنتجات).

Bubblewrap هي مجموعة من المكتبات مفتوحة المصدر وأداة سطر أوامر (CLI) لنظام Node.js. طوّر فريق Google Chrome أداة Bubblewrap لمساعدة المطوّرين في إنشاء مشروع Android وتصميمه وتوقيعه، وهو مشروع يتيح تشغيل تطبيق الويب التقدّمي (PWA) على شكل نشاط ويب موثوق (TWA).

PWABuilder هو مشروع مفتوح المصدر طوّرته شركة Microsoft، ويتيح للمطوّرين إنشاء حِزم وتوقيع تطبيقات الويب التقدّمية لنشرها في متاجر مختلفة، بما في ذلك Microsoft Store و"متجر Google Play" وApp Store وMeta Quest Store، وذلك من خلال إدخال عنوان URL الخاص بتطبيق ويب تقدّمي وإدخال البيانات الوصفية للتطبيق أو تعديلها والنقر على الزر "إنشاء".

يستخدم PWABuilder مكتبة Bubblewrap في الخلفية لتجميع تطبيقات الويب التقدّمية لنظامَي التشغيل Android وChromeOS.

إذا كان التطبيق مثبَّتًا من قبل، يمكنك تخصيص تجربة المستخدم.

على سبيل المثال:

عدم الترويج لتثبيت تطبيق الويب التقدّمي إذا كان تطبيقك الآخر مثبَّتًا.
إعادة توجيه المستخدم من موقع إلكتروني للتسويق لمنتج ما إلى تطبيقك مباشرةً
تجميع بعض الوظائف، مثل الإشعارات، في التطبيق الآخر لمنع تكرار الإشعارات

لاستخدام واجهة برمجة التطبيقات Get Installed Related Apps، عليك إخبار تطبيقك بصفحتك، ثم إخبار صفحتك بتطبيقك. وبعد تحديد العلاقة بين الاثنين، يمكنك التحقّق مما إذا كان التطبيق المرتبط مثبّتًا.

لمنع المواقع الإلكترونية من اختبار مجموعة واسعة جدًا من تطبيقاتها، سيتم أخذ التطبيقات الثلاثة الأولى فقط المُدرَجة في بيان تطبيق الويب في الاعتبار.

كما هو الحال مع معظم واجهات برمجة التطبيقات الأخرى القوية على الويب، لا تتوفّر واجهة برمجة التطبيقات Get Installed Related Apps إلا عند عرضها عبر HTTPS.

ما هي Get Installed Related Apps API؟

يؤدي استدعاء طريقة navigator.getInstalledRelatedApps() غير متزامنة إلى عرض وعد يتم تنفيذه باستخدام مجموعة من العناصر التي تحتوي على تفاصيل حول التطبيقات التي:

مثبَّت على الجهاز الحالي
المحدّد في حقل related_applications من بيان تطبيق الويب،
أن تكون لديك علاقة تم إثباتها بصفحة يتم فيها استدعاء الطريقة navigator.getInstalledRelatedApps() (راجِع الأقسام التالية للحصول على التفاصيل).

const installedRelatedApps = await navigator.getInstalledRelatedApps?.();

سيؤدي طلب console.log(installedRelatedApps) إلى عرض نتيجة مشابهة لما يلي:

[
  {
    platform: "webapp",
    id: "https://example.com/?utm_source=home_screen",
    url: "https://example.com/manifest.json"
  },
  {
    platform: "play",
    id: "com.example.twa",
    url: "https://play.google.com/store/apps/details?id=com.example.twa",
    version: "0.1.0"
  }
]

على سبيل المثال، للتحقّق ممّا إذا كانت أي تطبيقات ذات صلة مثبَّتة على جهاز المستخدِم، يمكنك استخدام السطر الواحد التالي:

const hasInstalledRelatedApps = !!(await navigator.getInstalledRelatedApps?.())?.length;

إذا كنت تعرف معرّف الحزمة، يمكنك استخدام السطر الواحد التالي للحصول على رقم إصدار تطبيق Android ذي الصلة المثبَّت:

const installedRelatedAndroidAppVersion = (await navigator.getInstalledRelatedApps?.())?.find(app => app.id === 'com.example.twa')?.version;

وهذا يعني أنّ الطريقة navigator.getInstalledRelatedApps() ستستمر في عرض التطبيقات ذات الصلة المثبَّتة حتى إذا كان إصدارها أقل من min_version أو إذا كانت شهادة التوقيع لا تتطابق مع أي fingerprints تم الإعلان عنه في الحقل related_applications من بيان تطبيق الويب.

أنواع التطبيقات المتوافقة التي يمكنك التحقّق منها

نوع التطبيق	يمكن التحقّق من
تطبيق Android	على أجهزة Android فقط: الإصدار 80 من Chrome أو الإصدارات الأحدث
تطبيق Universal Windows Platform (UWP)	على أجهزة Windows فقط: الإصدار 85 من Chrome أو الإصدارات الأحدث الإصدار 85 من Edge أو الإصدارات الأحدث
تطبيق ويب تقدّمي (PWA) مثبَّت في النطاق نفسه على المصدر نفسه	Android: الإصدار 84 من Chrome أو الإصدارات الأحدث الكمبيوتر المكتبي (Windows وmacOS وLinux وChromeOS): الإصدار 140 من Chrome أو الإصدارات الأحدث الإصدار 140 من Edge أو الإصدارات الأحدث
تطبيق الويب التقدّمي (PWA) المثبَّت في نطاق مختلف على المصدر نفسه أو مصدر مختلف	على أجهزة Android فقط: الإصدار 84 من Chrome أو الإصدارات الأحدث

التأكّد من تثبيت تطبيق Android

يمكن لموقعك الإلكتروني التحقّق مما إذا كان تطبيق Android مثبَّتًا.

على أجهزة Android فقط: الإصدار 80 من Chrome أو الإصدارات الأحدث

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

عليك أولاً تعديل تطبيق Android لتحديد العلاقة بين موقعك الإلكتروني وتطبيق Android باستخدام نظام Digital Asset Links. يؤكّد ذلك أنّه يمكن لموقعك الإلكتروني فقط التحقّق من تثبيت تطبيق Android.

في AndroidManifest.xml تطبيق Android، أضِف إدخال asset_statements:

<manifest>
  <application>
   …
    <meta-data android:name="asset_statements" android:resource="@string/asset_statements" />
   …
  </application>
</manifest>

بعد ذلك، في strings.xml، أضِف بيان مواد العرض التالي، وعدِّل site باستخدام نطاقك. تأكَّد من تضمين أحرف الهروب.

<string name="asset_statements">
  [{
    \"relation\": [\"delegate_permission/common.handle_all_urls\"],
    \"target\": {
      \"namespace\": \"web\",
      \"site\": \"https://example.com\"
    }
  }]
</string>

بعد اكتمال العملية، ثبِّت التطبيق المُعدَّل على الجهاز أو انشره على "متجر Google Play" أو أي من منصات توزيع تطبيقات Android الأخرى.

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

بعد ذلك، أخبِر موقعك الإلكتروني عن تطبيق Android من خلال إضافة بيان تطبيق ويب إلى صفحتك. يجب أن يتضمّن ملف البيان السمة related_applications، وهي عبارة عن مصفوفة تقدّم تفاصيل حول تطبيقك، بما في ذلك platform وid.

يجب أن يكون platform هو play
‫id هو معرّف حزمة Android

{
  "related_applications": [{
    "platform": "play",
    "id": "com.android.chrome"
  }]
}

التأكّد من تثبيت التطبيق

أخيرًا، استدعِ الدالة غير المتزامنة navigator.getInstalledRelatedApps() للتحقّق مما إذا كان تطبيق Android مثبّتًا.

التحقّق من تثبيت تطبيق Windows (UWP)

يمكن لموقعك الإلكتروني التحقّق مما إذا كان تطبيق Windows (الذي تم إنشاؤه باستخدام "النظام الأساسي العالمي" (UWP)) مثبّتًا.

في نظام التشغيل Windows فقط: الإصدار 85 من Chrome أو الإصدارات الأحدث، الإصدار 85 من Edge أو الإصدارات الأحدث

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

عليك تعديل تطبيق Windows لتحديد العلاقة بين موقعك الإلكتروني وتطبيق Windows باستخدام معالجات معرّف الموارد المنتظم (URI). يؤكّد ذلك أنّه يمكن لموقعك الإلكتروني فقط التحقّق مما إذا كان تطبيق Windows مثبّتًا.

أضِف تسجيل إضافة Windows.appUriHandler إلى ملف البيان Package.appxmanifest لتطبيقك. على سبيل المثال، إذا كان عنوان موقعك الإلكتروني هو example.com، عليك إضافة الإدخال التالي في ملف البيان الخاص بتطبيقك:

<Applications>
  <Application Id="App" ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="example.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

ملاحظة: قد تحتاج إلى إضافة مساحة الاسم uap3 إلى السمة <Package>.

بعد ذلك، أنشئ ملف JSON (بدون امتداد الملف .json) باسم windows-app-web-link وقدِّم اسم حزمة تطبيقك. ضَع هذا الملف إما في جذر الخادم أو في الدليل /.well-known/. يمكنك العثور على اسم مجموعة الحزمة في قسم "التعبئة" في مصمم بيان التطبيق.

[{
  "packageFamilyName": "MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ]
}]

اطّلِع على تفعيل التطبيقات للمواقع الإلكترونية باستخدام معالجات معرّف الموارد المنتظم (URI) للتطبيقات للحصول على التفاصيل الكاملة حول إعداد معالجات معرّف الموارد المنتظم (URI).

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

بعد ذلك، عليك إخبار موقعك الإلكتروني بتطبيق Windows من خلال إضافة بيان تطبيق ويب إلى صفحتك. يجب أن يتضمّن ملف البيان السمة related_applications، وهي عبارة عن مصفوفة تقدّم تفاصيل حول تطبيقك، بما في ذلك platform وid.

يجب أن يكون platform هو windows
‫id هو اسم مجموعة حِزم تطبيقك، ويتم إلحاقه بقيمة <Application> Id في ملف Package.appxmanifest.

{
  "related_applications": [{
    "platform": "windows",
    "id": "MyApp_9jmtgj1pbbz6e!App"
  }]
}

التأكّد من تثبيت التطبيق

أخيرًا، استدعِ الدالة غير المتزامنة navigator.getInstalledRelatedApps() للتحقّق مما إذا كان تطبيق Windows مثبّتًا.

اطّلِع على هذا العرض التوضيحي.

التحقّق مما إذا كان تطبيق الويب التقدّمي مثبَّتًا (ضمن النطاق)

يمكن لتطبيق الويب التقدّمي التحقّق مما إذا كان مثبّتًا من قبل. في هذه الحالة، يجب أن تكون الصفحة التي تُرسل الطلب على النطاق نفسه وضمن نطاق تطبيق الويب التقدّمي، كما هو محدّد في النطاق في بيان تطبيق الويب.

متاح للاستخدام في:

‫Android: الإصدار 84 من Chrome أو الإصدارات الأحدث

أجهزة الكمبيوتر (Windows وmacOS وLinux وChromeOS): الإصدار 140 من Chrome أو الإصدارات الأحدث، الإصدار 140 من Edge أو الإصدارات الأحدث

إخبار تطبيق الويب التقدّمي عن نفسه

يمكنك تعريف تطبيق الويب التقدّمي (PWA) بنفسه من خلال إضافة إدخال related_applications في بيان تطبيق الويب الخاص بتطبيق الويب التقدّمي (PWA).

يجب أن يكون platform هو webapp
url هو المسار (يمكن أن يكون نسبيًا) إلى بيان تطبيق الويب التقدّمي (PWA)
‫id هو معرّف تطبيق الويب الذي تم تعريفه في الحقل id في بيان تطبيق الويب أو الذي يحسبه المتصفّح (مطلوب لأجهزة الكمبيوتر، وليس مطلوبًا لنظام Android)

{
  …
  "scope": "/",
  "start_url": "/?utm_source=home_screen",
  "related_applications": [{
    "platform": "webapp",
    "url": "/manifest.json",
    "id": "https://example.com/?utm_source=home_screen"
  }],
  …
}

التحقّق مما إذا كان تطبيق الويب التقدّمي مثبّتًا

أخيرًا، استدعِ الدالة غير المتزامنة navigator.getInstalledRelatedApps() من نطاق تطبيق الويب التقدّمي للتحقّق من تثبيته. إذا تم استدعاء navigator.getInstalledRelatedApps() خارج نطاق تطبيق الويب التقدّمي، سيتم عرض []. يُرجى الاطلاع على القسم التالي للحصول على التفاصيل.

التحقّق مما إذا كان "تطبيق الويب التقدّمي" مثبَّتًا (خارج النطاق)

يمكن لموقعك الإلكتروني التحقّق مما إذا كان تطبيق الويب التقدّمي مثبَّتًا، حتى إذا كانت الصفحة خارج نطاق تطبيق الويب التقدّمي. على سبيل المثال، يمكن لصفحة مقصودة يتم عرضها من /landing/ التحقّق مما إذا كان تطبيق الويب التقدّمي الذي يتم عرضه من /pwa/ مثبّتًا، أو إذا كانت صفحتك المقصودة يتم عرضها من www.example.com وكان تطبيق الويب التقدّمي يتم عرضه من app.example.com.

متاح للاستخدام في:

على أجهزة Android فقط: الإصدار 84 من Chrome أو الإصدارات الأحدث

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

عليك أولاً إضافة روابط الأصول الرقمية إلى الخادم الذي يتم عرض تطبيق الويب التقدّمي منه. سيساعد ذلك في تحديد العلاقة بين موقعك الإلكتروني وتطبيق الويب التقدّمي، كما سيتحقّق من أنّ موقعك الإلكتروني فقط هو الذي يمكنه التحقّق من تثبيت تطبيق الويب التقدّمي.

أضِف ملف assetlinks.json إلى الدليل /.well-known/ الخاص بالنطاق الذي يتضمّن تطبيق الويب التقدّمي، مثل app.example.com. في السمة site، أدخِل المسار الكامل إلى بيان تطبيق الويب الذي سيُجري عملية التحقّق (وليس بيان تطبيق الويب الخاص بتطبيق الويب التقدّمي).

// Served from https://app.example.com/.well-known/assetlinks.json
[
  {
    "relation": ["delegate_permission/common.query_webapk"],
    "target": {
      "namespace": "web",
      "site": "https://www.example.com/manifest.json"
    }
  }
]

بعد ذلك، عليك إخبار موقعك الإلكتروني بتطبيق PWA من خلال إضافة بيان تطبيق ويب إلى صفحتك. يجب أن يتضمّن ملف البيان السمة related_applications، وهي عبارة عن مصفوفة تقدّم تفاصيل حول تطبيق الويب التقدّمي، بما في ذلك platform وurl.

يجب أن يكون platform هو webapp
url هو المسار الكامل إلى بيان تطبيق الويب التقدّمي (PWA)

{
  "related_applications": [{
    "platform": "webapp",
    "url": "https://app.example.com/manifest.json"
  }]
}

التحقّق مما إذا كان تطبيق الويب التقدّمي مثبّتًا

أخيرًا، استدعِ الدالة غير المتزامنة navigator.getInstalledRelatedApps() للتحقّق مما إذا كان تطبيق الويب التقدّمي مثبّتًا.

هل ما زالت لديك أسئلة؟

هل ما زالت لديك أسئلة؟ اطّلِع على العلامة getInstalledRelatedApps على StackOverflow لمعرفة ما إذا كان أي مستخدم آخر قد طرح أسئلة مشابهة. إذا لم يكن كذلك، اطرح سؤالك هناك، وتأكَّد من وضع العلامة progressive-web-apps عليه. يراقب فريقنا هذه العلامة بشكل متكرّر ويحاول الإجابة عن أسئلتك.

الملاحظات

هل عثرت على خطأ في تنفيذ Chrome؟ أو هل يختلف التنفيذ عن المواصفات؟

يمكنك الإبلاغ عن الخطأ على الرابط https://new.crbug.com. يُرجى تضمين أكبر قدر ممكن من التفاصيل وتقديم تعليمات لإعادة إنتاج الخطأ وإدخال Mobile>WebAPKs في مربّع المكوّنات.

روابط مفيدة

شكرًا

نشكر Sunggook Chue من Microsoft على المساعدة في تقديم تفاصيل حول اختبار تطبيقات Windows، ونشكر Rayan Kanso على المساعدة في تقديم تفاصيل حول Chrome.

هل تم تثبيت تطبيقك؟ ستخبرك واجهة برمجة التطبيقات Get Installed Related Apps API بذلك. تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

ما هي Get Installed Related Apps API؟

أنواع التطبيقات المتوافقة التي يمكنك التحقّق منها

التأكّد من تثبيت تطبيق Android

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

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

التأكّد من تثبيت التطبيق

التحقّق من تثبيت تطبيق Windows (UWP)

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

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

التأكّد من تثبيت التطبيق

التحقّق مما إذا كان تطبيق الويب التقدّمي مثبَّتًا (ضمن النطاق)

إخبار تطبيق الويب التقدّمي عن نفسه

التحقّق مما إذا كان تطبيق الويب التقدّمي مثبّتًا

التحقّق مما إذا كان "تطبيق الويب التقدّمي" مثبَّتًا (خارج النطاق)

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

التحقّق مما إذا كان تطبيق الويب التقدّمي مثبّتًا

هل ما زالت لديك أسئلة؟

الملاحظات

روابط مفيدة

شكرًا

هل تم تثبيت تطبيقك؟ ستخبرك واجهة برمجة التطبيقات Get Installed Related Apps API بذلك.