كيفية توفير تجربة التثبيت داخل التطبيق

Pete LePage

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

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

عند التفكير في ما إذا كنت تريد الترويج للتثبيت، ننصحك بالتفكير في كيفية استخدام المستخدمين لتطبيق الويب التقدّمي (PWA) بشكلٍ عام. على سبيل المثال، إذا كانت هناك مجموعة من المستخدمين يستخدمون تطبيقك المتوافق مع الأجهزة الجوّالة المتعددة مرات في الأسبوع، قد يستفيد هؤلاء المستخدمون من الراحة الإضافية التي يوفّرها إطلاق تطبيقك من الشاشة الرئيسية للهاتف أو من قائمة "ابدأ" في نظام التشغيل لأجهزة الكمبيوتر المكتبي. تستفيد أيضًا بعض تطبيقات الإنتاجية والترفيه من مساحة الشاشة الإضافية التي يتم إنشاؤها عن طريق إزالة أشرطة أدوات المتصفّح من النافذة في أوضاع standalone أو minimal-ui أو window-control-overlay المثبّتة.

المتطلبات الأساسية

قبل البدء، تأكَّد من أنّ تطبيقك المتوافق مع الأجهزة الجوّالة يستوفي متطلبات التثبيت، والتي تشمل عادةً توفُّر بيان تطبيق ويب.

الترويج للتثبيت

لإظهار أنّ تطبيق الويب التقدّمي قابل للتثبيت، ولتقديم مسار تثبيت مخصّص داخل التطبيق:

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

انتظِر حدث beforeinstallprompt.

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

// Initialize deferredPrompt for use later to show browser install prompt.
let deferredPrompt;

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent the mini-infobar from appearing on mobile
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI notify the user they can install the PWA
  showInstallPromotion();
  // Optionally, send analytics event that PWA install promo was shown.
  console.log(`'beforeinstallprompt' event was fired.`);
});

خطوات التثبيت داخل التطبيق

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

buttonInstall.addEventListener('click', async () => {
  // Hide the app provided install promotion
  hideInstallPromotion();
  // Show the install prompt
  deferredPrompt.prompt();
  // Wait for the user to respond to the prompt
  const { outcome } = await deferredPrompt.userChoice;
  // Optionally, send analytics event with outcome of user choice
  console.log(`User response to the install prompt: ${outcome}`);
  // We've used the prompt and can't use it again, throw it away
  deferredPrompt = null;
});

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

رصد حالات تثبيت تطبيق الويب المتوافق مع الأجهزة الجوّالة بنجاح

يمكنك استخدام السمة userChoice لتحديد ما إذا كان المستخدم قد ثبَّت تطبيقك من داخل واجهة المستخدم. ولكن إذا ثبَّت المستخدم تطبيقك المتوافق مع الأجهزة الجوّالة (PWA) من شريط العناوين أو مكوّن آخر في المتصفّح، لن يساعدك userChoice. بدلاً من ذلك، عليك مراقبة الحدث appinstalled الذي يتم تشغيله عند تثبيت تطبيقك المتوافق مع الأجهزة الجوّالة (PWA)، بغض النظر عن الآلية المستخدَمة لتثبيته.

window.addEventListener('appinstalled', () => {
  // Hide the app-provided install promotion
  hideInstallPromotion();
  // Clear the deferredPrompt so it can be garbage collected
  deferredPrompt = null;
  // Optionally, send analytics event to indicate successful install
  console.log('PWA was installed');
});

رصد كيفية إطلاق تطبيق الويب التقدّمي

تشير طلبية الوسائط display-mode في CSS إلى كيفية تشغيل تطبيق الويب التقدّمي، سواءً في علامة تبويب متصفّح أو كتطبيق ويب تقدّمي مثبّت. يتيح ذلك تطبيق تصاميم مختلفة حسب طريقة تشغيل التطبيق. على سبيل المثال، يمكنك ضبطه لإخفاء زر التثبيت دائمًا وتوفير زر الرجوع عند تشغيله كتطبيق PWA مثبَّت.

تتبُّع كيفية إطلاق تطبيق الويب التقدّمي

لتتبُّع كيفية إطلاق المستخدمين لتطبيقك المتوافق مع الأجهزة الجوّالة، استخدِم matchMedia() لاختبار طلب الوسائط display-mode.

function getPWADisplayMode() {
  if (document.referrer.startsWith('android-app://'))
    return 'twa';
  if (window.matchMedia('(display-mode: browser)').matches)
    return 'browser';
  if (window.matchMedia('(display-mode: standalone)').matches || navigator.standalone)
    return 'standalone';
  if (window.matchMedia('(display-mode: minimal-ui)').matches)
    return 'minimal-ui';
  if (window.matchMedia('(display-mode: fullscreen)').matches)
    return 'fullscreen';
  if (window.matchMedia('(display-mode: window-controls-overlay)').matches)
    return 'window-controls-overlay';

  return 'unknown';
}

تتبُّع حالات تغيير وضع العرض

لتتبُّع ما إذا كان المستخدم يغيّر بين browser وأوضاع العرض الأخرى، راقِب التغييرات في طلب عرض الوسائط display-mode.

// Replace "standalone" with the display mode used in your manifest
window.matchMedia('(display-mode: standalone)').addEventListener('change', () => {
  // Log display mode change to analytics
  console.log('DISPLAY_MODE_CHANGED', getPWADisplayMode());
});

تعديل واجهة المستخدم استنادًا إلى وضع العرض الحالي

لتطبيق لون خلفية مختلف على تطبيق متوافق مع مبادرة التطبيقات المتوافقة مع الأجهزة الجوّالة عند تشغيله كتطبيق متوافق مع مبادرة التطبيقات المتوافقة مع الأجهزة الجوّالة، استخدِم التنسيق الشرطي لصفحات الويب (CSS):

@media all and (display-mode: standalone) {
  body {
    background-color: yellow;
  }
}

تعديل رمز تطبيقك واسمه

ماذا لو كنت بحاجة إلى تعديل اسم تطبيقك أو تقديم رموز جديدة؟ اطّلِع على كيفية تعامل Chrome مع تحديثات بيان تطبيق الويب لمعرفة وقت ظهور هذه التغييرات وكيفية ظهورها في Chrome.