تتيح لك العديد من المتصفحات تفعيل تطبيق الويب التقدّمي (PWA) والترويج له مباشرةً من خلال واجهة المستخدم. إنّ التثبيت (يُشار إليه سابقًا باسم "إضافة إلى الشاشة الرئيسية") يتيح للمستخدمين تثبيت تطبيق الويب التقدّمي (PWA) على أجهزتهم الجوّالة أو أجهزة الكمبيوتر المكتبي. يؤدي تثبيت تطبيق الويب التقدّمي (PWA) إلى إضافته إلى مشغّل المستخدم حتى يمكن تشغيله مثل أي تطبيق آخر مثبَّت.
بالإضافة إلى تجربة التثبيت التي يوفّرها المتصفّح، يمكنك توفير مسار تثبيت مخصّص لك مباشرةً من داخل تطبيقك.
![زر تثبيت التطبيق المتوفّر في تطبيق الويب التقدّمي Spotify](https://web.dev/static/articles/customize-install/image/install-app-button-provid-c69a76f7a7ce5.png?authuser=6&hl=ar)
عند التفكير في الترويج للتثبيت، ضَع في اعتبارك طريقة استخدام المستخدمين عادةً
لتطبيق الويب التقدّمي (PWA) الخاص بك. على سبيل المثال، إذا كان هناك مجموعة من المستخدمين الذين يستخدمون تطبيق الويب التقدّمي (PWA) عدة مرات في الأسبوع، قد يستفيد هؤلاء المستخدمون من ميزة تشغيل التطبيق من الشاشة الرئيسية للهاتف أو من قائمة "البدء" في نظام تشغيل الكمبيوتر المكتبي. تستفيد بعض تطبيقات الإنتاجية والترفيه أيضًا من مساحة الشاشة الإضافية التي يتم إنشاؤها من خلال إزالة أشرطة أدوات المتصفّح من النافذة في الوضعَين standalone
أو minimal-ui
المثبَّتَين.
المتطلبات الأساسية
قبل البدء، تأكَّد من أنّ تطبيق الويب التقدّمي (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
.
رصد وقت تثبيت تطبيق الويب التقدّمي (PWA) بنجاح
يمكنك استخدام السمة 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');
});
التعرّف على كيفية إطلاق تطبيق الويب التقدّمي (PWA)
يشير الاستعلام عن وسائط display-mode
في CSS إلى كيفية إطلاق تطبيق الويب التقدّمي (PWA)، إمّا في علامة تبويب متصفّح أو كتطبيق ويب تقدّمي مثبّت. هذا يجعل من الممكن تطبيق أنماط مختلفة
اعتمادًا على كيفية إطلاق التطبيق. على سبيل المثال، يمكنك ضبطه على إخفاء زر التثبيت دائمًا وتوفير زر الرجوع عند تشغيله كتطبيق PWA مثبَّت.
تتبُّع كيفية إطلاق تطبيق الويب التقدّمي (PWA)
لتتبُّع كيفية تشغيل المستخدمين لتطبيق الويب التقدّمي (PWA)، استخدِم matchMedia()
لاختبار الاستعلام عن الوسائط بخصوص display-mode
. لا تتوفّر هذه الميزة في متصفّح Safari على أجهزة iOS، لذا يجب بدلاً من ذلك الاطّلاع على navigator.standalone
التي تعرض قيمة منطقية تشير إلى ما إذا كان المتصفّح يعمل في الوضع المستقل.
function getPWADisplayMode() {
const isStandalone = window.matchMedia('(display-mode: standalone)').matches;
if (document.referrer.startsWith('android-app://')) {
return 'twa';
} else if (navigator.standalone || isStandalone) {
return 'standalone';
}
return 'browser';
}
التتبُّع عند تغيير وضع العرض
لتتبُّع ما إذا كان المستخدم يغيّر بين standalone
وbrowser tab
، يمكنك الاستماع إلى
التغييرات في الاستعلام عن الوسائط display-mode
.
window.matchMedia('(display-mode: standalone)').addEventListener('change', (evt) => {
let displayMode = 'browser';
if (evt.matches) {
displayMode = 'standalone';
}
// Log display mode change to analytics
console.log('DISPLAY_MODE_CHANGED', displayMode);
});
تعديل واجهة المستخدم استنادًا إلى وضع العرض الحالي
لاستخدام لون خلفية مختلف لتطبيق PWA عند تشغيله كتطبيق PWA مثبَّت، استخدِم لغة CSS الشرطية:
@media all and (display-mode: standalone) {
body {
background-color: yellow;
}
}
تعديل رمز التطبيق واسمه
ماذا لو كنت بحاجة إلى تعديل اسم التطبيق أو تقديم رموز جديدة؟ يمكنك الاطّلاع على المقالة طريقة معالجة Chrome لتحديثات بيان تطبيق الويب لمعرفة وقت وطريقة ظهور هذه التغييرات في Chrome.