تتيح لك العديد من المتصفحات تفعيل أو ترقية عملية تثبيت تطبيق الويب التقدّمي (PWA) مباشرةً من خلال واجهة المستخدم الخاصة به. يتيح التثبيت (المعروف سابقًا باسم "الإضافة إلى الشاشة الرئيسية") للمستخدمين تثبيت صفحة الويب المتوافقة مع الأجهزة الجوّالة على أجهزتهم الجوّالة أو أجهزة الكمبيوتر المكتبي. يؤدي تثبيت تطبيق PWA إلى إضافته إلى ملف التمهيد الخاص بالمستخدم كي يتمكّن من تشغيله مثل أي تطبيق آخر مثبّت.
بالإضافة إلى تجربة التثبيت التي يوفرها المتصفح، يمكنك توفير خطوات تثبيت مخصصة مباشرة داخل تطبيقك.
عند التفكير في الترويج للتثبيت، ضع في اعتبارك كيف يستخدم المستخدمون تطبيق الويب التقدّمي (PWA) عادةً. على سبيل المثال، إذا كانت هناك مجموعة من المستخدمين يستخدمون تطبيق الويب التقدّمي (PWA) عدة مرات في الأسبوع، قد يستفيد هؤلاء المستخدمون من الراحة الإضافية
لإطلاق تطبيقك من شاشة رئيسية للهاتف أو من قائمة "ابدأ" (Start) في نظام تشغيل على الكمبيوتر المكتبي. تستفيد أيضًا بعض تطبيقات الإنتاجية والترفيه
من مساحة الشاشة الإضافية التي يتم إنشاؤها عن طريق إزالة أشرطة أدوات المتصفّح من
النافذة في أوضاع standalone أو minimal-ui أو window-control-overlay المثبّتة.
المتطلبات الأساسية
قبل البدء، تأكَّد من أنّ تطبيق الويب التقدّمي (PWA) يستوفي متطلبات قابلية التثبيت، والتي تتضمّن عادةً الحصول على بيان تطبيق ويب.
ترقية التثبيت
لإظهار أنّ تطبيق الويب التقدّمي قابل للتثبيت، ولتقديم مسار تثبيت مخصّص داخل التطبيق:
- انتظِر الحدث
beforeinstallprompt. - احفظ حدث
beforeinstallpromptلبدء عملية التثبيت لاحقًا. - أطلِع المستخدم على أنّ تطبيق الويب التقدمي (PWA) قابل للتثبيت، وقدِّم زرًا أو عنصرًا آخر لبدء عملية التثبيت داخل التطبيق.
انتظِر حدث beforeinstallprompt.
إذا استوفى تطبيق الويب التقدّمي معايير التثبيت المطلوبة، ينشط المتصفّح حدث beforeinstallprompt. احفظ مرجعًا للحدث، وعدِّل واجهة المستخدم للإشارة إلى أنّه بإمكان المستخدم تثبيت تطبيق الويب التقدّمي (PWA).
// 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). ويعرض للمستخدم مربّع حوار تثبيت مشروط، ويطلب منه تأكيد أنّه يريد تثبيت تطبيق الويب التقدّمي (PWA).
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.