تاريخ النشر: 14 شباط (فبراير) 2020
تتيح لك العديد من المتصفّحات تفعيل عملية تثبيت تطبيق الويب التقدّمي (PWA) والترويج لها مباشرةً من خلال واجهة المستخدم. تتيح عملية التثبيت (المعروفة سابقًا باسم "إضافة إلى الشاشة الرئيسية") للمستخدمين إضافة تطبيق الويب التقدّمي إلى أجهزتهم الجوّالة أو أجهزة الكمبيوتر. يؤدي تثبيت تطبيق ويب تقدّمي إلى إضافته إلى مشغّل التطبيقات الخاص بالمستخدم، ما يتيح تشغيله مثل أي تطبيق آخر مثبَّت.
بالإضافة إلى تجربة التثبيت التي يوفّرها المتصفّح، يمكنك توفير مسار تثبيت مخصّص خاص بك مباشرةً داخل تطبيقك.
عند التفكير في الترويج للتثبيت، يجب مراعاة الطريقة التي يستخدم بها المستخدمون عادةً تطبيقك التقدّمي على الويب. على سبيل المثال، إذا كانت هناك مجموعة من المستخدمين الذين يستعملون تطبيق PWA عدة مرات في الأسبوع، قد يستفيد هؤلاء المستخدمون من سهولة إطلاق تطبيقك من الشاشة الرئيسية للهاتف أو من قائمة "ابدأ" في نظام تشغيل على الكمبيوتر المكتبي. تستفيد بعض تطبيقات الإنتاجية والترفيه أيضًا من مساحة الشاشة الإضافية التي يتم توفيرها من خلال إزالة أشرطة أدوات المتصفح من النافذة في أوضاع standalone أو minimal-ui أو window-control-overlay المثبّتة.
المتطلبات الأساسية
قبل البدء، تأكَّد من أنّ تطبيق الويب التقدّمي يستوفي متطلبات التثبيت، والتي تتضمّن عادةً بيان تطبيق الويب.
الترويج للتثبيت
لإظهار أنّ تطبيق الويب التقدّمي قابل للتثبيت، ولتوفير مسار مخصّص لتثبيت التطبيق:
- استمع إلى الحدث
beforeinstallprompt. - احفظ حدث
beforeinstallpromptحتى يتمكّن من تشغيل مسار التثبيت لاحقًا. - إعلام المستخدم بأنّ تطبيق الويب التقدّمي (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 لتحديد ما إذا كان المستخدم قد ثبّت تطبيقك من داخل واجهة المستخدم. ومع ذلك، إذا ثبّت المستخدم تطبيق الويب التقدّمي من شريط العناوين أو أحد مكونات المتصفح الأخرى، لن يساعدك userChoice.
بدلاً من ذلك، عليك معالجة الحدث appinstalled الذي يتم تنشيطه كلما تم تثبيت تطبيق الويب التقدّمي، بغض النظر عن الآلية المستخدَمة لتثبيته.
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());
});
تعديل واجهة المستخدم استنادًا إلى وضع العرض الحالي
لتطبيق لون خلفية مختلف على تطبيق ويب تقدّمي (PWA) عند تشغيله كتطبيق ويب تقدّمي مثبَّت، استخدِم CSS الشرطية:
@media all and (display-mode: standalone) {
body {
background-color: yellow;
}
}
تعديل رمز تطبيقك واسمه
ماذا لو كنت بحاجة إلى تعديل اسم تطبيقك أو تقديم رموز جديدة؟ يمكنك الاطّلاع على الطريقة التي يتعامل بها Chrome مع تحديثات بيان تطبيق الويب لمعرفة متى وكيف يتم عرض هذه التغييرات في Chrome.