چگونه تجربه نصب درون برنامه ای خود را ارائه دهید

بسیاری از مرورگرها به شما این امکان را می دهند که نصب برنامه وب پیشرو (PWA) خود را مستقیماً در رابط کاربری آن فعال و ترویج کنید. نصب (گاهی اوقات قبلاً به عنوان افزودن به صفحه اصلی نامیده می شد) به کاربران امکان می دهد PWA شما را روی دستگاه تلفن همراه یا دسکتاپ خود نصب کنند. نصب PWA آن را به راه‌انداز کاربر اضافه می‌کند تا بتواند مانند هر برنامه نصب‌شده دیگری اجرا شود.

علاوه بر تجربه نصب ارائه شده توسط مرورگر ، می توانید جریان نصب سفارشی خود را مستقیماً در برنامه خود ارائه دهید.

دکمه برنامه را نصب کنید که در Spotify PWA ارائه شده است
دکمه «نصب برنامه» ارائه شده در Spotify PWA.

هنگام بررسی اینکه آیا نصب را ارتقا دهید، نحوه استفاده کاربران از PWA را در نظر بگیرید. به عنوان مثال، اگر مجموعه‌ای از کاربران هستند که چندین بار در هفته از PWA شما استفاده می‌کنند، این کاربران ممکن است از راحتی اضافی راه‌اندازی برنامه شما از صفحه اصلی تلفن یا از منوی Start در یک سیستم عامل دسکتاپ بهره ببرند. برخی از برنامه‌های بهره‌وری و سرگرمی نیز از فضای صفحه نمایش اضافی ایجاد شده با حذف نوار ابزار مرورگر از پنجره در حالت‌های standalone نصب شده، minimal-ui یا window-control-overlay ، بهره می‌برند.

پیش نیازها

قبل از شروع، مطمئن شوید که PWA شما الزامات نصب را برآورده می کند، که معمولاً شامل داشتن مانیفست برنامه وب است.

ترویج نصب

برای نشان دادن اینکه برنامه وب پیشرفته شما قابل نصب است و برای ارائه یک جریان نصب سفارشی درون برنامه:

  1. به رویداد beforeinstallprompt گوش دهید.
  2. رویداد beforeinstallprompt را ذخیره کنید تا بتواند بعداً جریان نصب را راه‌اندازی کند.
  3. به کاربر هشدار دهید که 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 را پیگیری کنید

برای ردیابی اینکه کاربران چگونه 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 هنگام راه‌اندازی به عنوان PWA نصب شده، از CSS شرطی استفاده کنید:

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

نماد و نام برنامه خود را به روز کنید

اگر بخواهید نام برنامه خود را به روز کنید یا نمادهای جدیدی ارائه دهید، چه؟ بررسی کنید Chrome چگونه به‌روزرسانی‌های مانیفست برنامه وب را مدیریت می‌کند تا ببینید این تغییرات چه زمانی و چگونه در Chrome منعکس می‌شوند.

،

بسیاری از مرورگرها به شما این امکان را می دهند که نصب برنامه وب پیشرو (PWA) خود را مستقیماً در رابط کاربری آن فعال و ترویج کنید. نصب (گاهی اوقات قبلاً به عنوان افزودن به صفحه اصلی نامیده می شد) به کاربران امکان می دهد PWA شما را روی دستگاه تلفن همراه یا دسکتاپ خود نصب کنند. نصب PWA آن را به راه‌انداز کاربر اضافه می‌کند تا بتواند مانند هر برنامه نصب‌شده دیگری اجرا شود.

علاوه بر تجربه نصب ارائه شده توسط مرورگر ، می توانید جریان نصب سفارشی خود را مستقیماً در برنامه خود ارائه دهید.

دکمه برنامه را نصب کنید که در Spotify PWA ارائه شده است
دکمه «نصب برنامه» ارائه شده در Spotify PWA.

هنگام بررسی اینکه آیا نصب را ارتقا دهید، نحوه استفاده کاربران از PWA را در نظر بگیرید. به عنوان مثال، اگر مجموعه‌ای از کاربران هستند که چندین بار در هفته از PWA شما استفاده می‌کنند، این کاربران ممکن است از راحتی اضافی راه‌اندازی برنامه شما از صفحه اصلی تلفن یا از منوی Start در یک سیستم عامل دسکتاپ بهره ببرند. برخی از برنامه‌های بهره‌وری و سرگرمی نیز از فضای صفحه نمایش اضافی ایجاد شده با حذف نوار ابزار مرورگر از پنجره در حالت‌های standalone نصب شده، minimal-ui یا window-control-overlay ، بهره می‌برند.

پیش نیازها

قبل از شروع، مطمئن شوید که PWA شما الزامات نصب را برآورده می کند، که معمولاً شامل داشتن مانیفست برنامه وب است.

ترویج نصب

برای نشان دادن اینکه برنامه وب پیشرفته شما قابل نصب است و برای ارائه یک جریان نصب سفارشی درون برنامه:

  1. به رویداد beforeinstallprompt گوش دهید.
  2. رویداد beforeinstallprompt را ذخیره کنید تا بتواند بعداً جریان نصب را راه‌اندازی کند.
  3. به کاربر هشدار دهید که 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 را پیگیری کنید

برای ردیابی اینکه کاربران چگونه 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 هنگام راه‌اندازی به عنوان PWA نصب شده، از CSS شرطی استفاده کنید:

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

نماد و نام برنامه خود را به روز کنید

اگر بخواهید نام برنامه خود را به روز کنید یا نمادهای جدیدی ارائه دهید، چه؟ بررسی کنید Chrome چگونه به‌روزرسانی‌های مانیفست برنامه وب را مدیریت می‌کند تا ببینید این تغییرات چه زمانی و چگونه در Chrome منعکس می‌شوند.