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

Pete LePage
Alexey Rodionov
Alexey Rodionov
X GitHub LinkedIn

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

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

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

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

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

ما هي 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;

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

نوع التطبيق يمكن التحقّق من
تطبيق 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 (الذي تم إنشاؤه باستخدام "النظام الأساسي العالمي") مثبّتًا.

متوافق مع:

  • في نظام التشغيل 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 هو المسار الكامل إلى بيان تطبيق الويب الخاص بتطبيق الويب التقدّمي
{
  "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.