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

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

ما المعايير؟

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

  • لم يتم تثبيت تطبيق الويب أو التطبيق المحلي على الجهاز حاليًا.
  • يتضمّن بيان تطبيق الويب الذي يتضمّن:
    • 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 لرمز التطبيق.