رسالة تثبيت تطبيق محلي

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

ما هي المعايير المتّبعة؟

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

  • لا تطبيق الويب ولا التطبيق الأصلي مثبَّتَان حاليًا على الجهاز.
  • يتضمّن بيان تطبيق الويب الذي يشمل:
    • short_name
    • name (يُستخدَم في طلب البانر)
    • icons بما في ذلك إصداران بحجم 192 بكسل و512 بكسل
    • prefer_related_applications هي true
    • عنصر related_applications يتضمّن معلومات عن التطبيق
  • يتم عرضها عبر HTTPS

سيتمّ تنشيط حدث beforeinstallprompt عند استيفاء هذه المعايير. يمكنك استخدامها لطلب تثبيت تطبيقك الأصلي من المستخدم.

سمات البيان المطلوبة

لطلب تثبيت تطبيقك الأصلي من المستخدم، عليك إضافة خاصيتين إلى ملف بيان تطبيق الويب، وهماprefer_related_applications و related_applications.

"prefer_related_applications": true,
"related_applications": [
    {
    "platform": "play",
    "id": "com.google.samples.apps.iosched"
    }
]

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

related_applications هو صفيف يحتوي على قائمة بالعناصر التي تُعلم المتصفّح بتطبيقك الأصلي المفضّل. يجب أن يتضمّن كل عنصر سمة platform وسمة id. حيث يكون platform play وid هو رقم تعريف تطبيق "متجر Play".

عرض طلب التثبيت

لعرض مربّع حوار التثبيت، عليك إجراء ما يلي:

  1. يرصد الحدث beforeinstallprompt.
  2. أطلِع المستخدم على أنّه يمكن تثبيت تطبيقك الأصلي باستخدام زر أو عنصر آخر سيؤدي إلى إنشاء حدث إيماءة مستخدِم.
  3. يمكنك عرض الطلب من خلال الاتصال بالرقم prompt() في الحدث beforeinstallprompt المحفوظ.

يرصد الميكروفون beforeinstallprompt

في حال استيفاء المعايير، سيُطلق Chrome حدث beforeinstallprompt. يمكنك استخدامها للإشارة إلى أنّه يمكن تثبيت تطبيقك، ثم الطلب من المستخدم تثبيته.

عند بدء حدث beforeinstallprompt، احفظ إشارة إلى الحدث، وعدِّل واجهة المستخدم للإشارة إلى أنّه يمكن للمستخدم تثبيت تطبيقك.

let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 67 and earlier from automatically showing the prompt
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
});

إبلاغ المستخدم بأنّه يمكن تثبيت تطبيقك

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

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 67 and earlier from automatically showing the prompt
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can add to home screen
  btnAdd.style.display = 'block';
});

عرض الطلب

لعرض طلب التثبيت، استخدِم الرمز prompt() في الحدث المحفوظ من داخل إيماءة المستخدم. سيظهر مربّع حوار مشروط يطلب من المستخدم إضافة تطبيقك إلى الشاشة الرئيسية.

بعد ذلك، انتظِر الوعد الذي يعرضه الحقل userChoice. يعرض الوعد outcome بعد أن يتم عرض الطلب ويردّ عليه المستخدم.

btnAdd.addEventListener('click', (e) => {
  // hide our user interface that shows our A2HS button
  btnAdd.style.display = 'none';
  // Show the prompt
  deferredPrompt.prompt();
  // Wait for the user to respond to the prompt
  deferredPrompt.userChoice
    .then((choiceResult) => {
      if (choiceResult.outcome === 'accepted') {
        console.log('User accepted the A2HS prompt');
      } else {
        console.log('User dismissed the A2HS prompt');
      }
      deferredPrompt = null;
    });
});

يمكنك استدعاء prompt() في الحدث المؤجّل مرة واحدة فقط. إذا أغلق المستخدِم النافذة المنبثقة، عليك الانتظار إلى أن يتم تنشيط الحدث beforeinstallprompt عند الانتقال إلى الصفحة التالية.

اعتبارات خاصة عند استخدام سياسة أمان المحتوى

إذا كان موقعك الإلكتروني يتضمّن سياسة أمان المحتوى تقييدية، احرص على إضافة *.googleusercontent.com إلى التوجيه img-src حتى تتمكّن Chrome من تنزيل الرمز المرتبط بتطبيقك من "متجر Play".

في بعض الحالات، قد يكون *.googleusercontent.com أكثر تفصيلاً من المطلوب. يمكن تحديد ذلك من خلال تصحيح الأخطاء عن بُعد على جهاز Android لتحديد عنوان URL لرمز التطبيق.