Add to Home screen

This translation is incomplete. Please help translate this article from English

เพิ่มไปยังหน้าจอหลัก (หรือ A2HS สําหรับระยะสั้น) เป็นคุณลักษณะที่มีอยู่ในเบราว์เซอร์สมาร์ทโฟนที่ทันสมัยที่ช่วยให้นักพัฒนาได้อย่างง่ายดายและสะดวกในการเพิ่มทางลัดไปยังหน้าจอหลักของพวกเขาเป็นตัวแทนของเว็บแอปที่ชื่นชอบ (หรือเว็บไซต์) เพื่อให้พวกเขาสามารถเข้าถึงมันได้ด้วยการแตะเพียงครั้งเดียว คู่มือนี้จะอธิบายวิธีการใช้ A2HS และสิ่งที่คุณต้องทําในฐานะนักพัฒนาซอฟต์แวร์เพื่อให้ผู้ใช้ใช้ประโยชน์จากมัน

ทําไมต้อง A2HS?

A2HS เป็นความคิดที่จะเป็นส่วนหนึ่งของปรัชญาโปรเกรสซีเว็บ App - ให้เว็บปพลิเคชันข้อดีประสบการณ์เช่นเดียวกับปพลิเคชันพื้นเมืองเพื่อให้พวกเขาสามารถแข่งขันในสงครามระบบนิเวศของวันนี้ ส่วนหนึ่งของนี้เป็นท่าทางง่ายๆในการเข้าถึงแอพพลิเคโดยแตะที่ไอคอนบนหน้าจอหลักของคุณแล้วมีมันจะปรากฏเรียบร้อยในหน้าต่างของตัวเอง A2HS ทําให้เป็นไปได้

เบราว์เซอร์ใดที่รองรับ A2HS?

A2HS ได้รับการสนับสนุนโดยมือถือ Chrome / Android เว็บวิวตั้งแต่รุ่น 31, โอเปร่าสําหรับ Android ตั้งแต่รุ่น 32 และ Firefox สําหรับ Android ตั้งแต่รุ่น 58

คุณจะใช้มันได้อย่างไร

เราได้เขียนเว็บไซต์ตัวอย่างง่ายมาก (ดูการสาธิตของเราอยู่และยังเห็นรหัสที่มา) ที่ไม่ทํามาก แต่ได้รับการพัฒนาด้วยรหัสที่จําเป็นเพื่อให้มันจะถูกเพิ่มไปยังหน้าจอหลักเช่นเดียวกับพนักงานบริการเพื่อให้สามารถใช้งานได้แบบออฟไลน์ ตัวอย่างแสดงชุดของภาพจิ้งจอก

หากคุณมี Firefox สําหรับ Android ใช้ได้ใช้เพื่อนําทางไปยังการสาธิตของเราที่ คุณจะเห็นภาพจิ้งจอก แต่สําคัญกว่าคุณจะเห็นไอคอน "บ้าน" ที่มีไอคอนบวก (+) อยู่ข้างใน - นี่คือไอคอน "เพิ่มหน้าจอโฮม" สําหรับไซต์ที่มีคุณลักษณะที่จําเป็นhttps://mdn.github.io/pwa-examples/a2hs/

แตะที่ปุ่มนี้จะแสดงแบนเนอร์ยืนยัน - การกดปุ่มใหญ่ + ADD TO HOME SCREENเสร็จสิ้นการดําเนินการเพิ่มแอพไปยังหน้าจอหลัก (หมายเหตุ: ใน Android 8 และสูงกว่า ระบบระดับ "เพิ่มไปยังหน้าจอหลัก" โต้ตอบสิทธิ์จะแสดงก่อน.

หากคุณมี Chrome มือถือที่มีอยู่ประสบการณ์จะแตกต่างกันเล็กน้อย เมื่อโหลดเว็บไซต์ของเราคุณจะเห็นป๊อปอัพติดตั้งแบนเนอร์ขึ้นถามว่าคุณต้องการที่จะเพิ่ม app นี้ไปยังหน้าจอหลักของคุณ

Note: You can find out a lot more about Chrome install banners from the article Web App Install Banners.

If you choose not to add it to your Home screen at this point, you can do so later using the Add to Home screen icon in the main Chrome menu.

Regardless of which browser you are using, when you choose to add the app to your Home screen, you'll see it appear along with a short title, in the same way that native apps do.

Tapping this icon opens it up, but as a fullscreen app, you'll no longer see the browser UI around it.

How do you make an app A2HS-ready?

To enable your app to be added to a Home screen, it needs the following:

  • To be served over HTTPs — the web is increasingly being moved in a more secure direction, and many modern web technologies (A2HS included) will work only on secure contexts.
  • To have a manifest file with the correct fields filled in, linked from the HTML head.
  • To have an appropriate icon available for displaying on the Home screen.
  • Chrome additionally requires the app to have a service worker registered (e.g., so it can function when offline).

Manifest

The web manifest is written in standard JSON format and should be placed somewhere inside your app directory (in the root is probably best) with the name (we've chosen ). It contains multiple fields that define certain information about the web app and how it should behave.somefilename.webmanifestmanifest.webmanifest

Note: The extension is specified in the Media type registration section of the specification, but generally browsers will support manifests with other appropriate extensions, e.g. ..webmanifest.json

The fields needed for A2HS are as follows:

  • background_color: Specifies a background color to be used in some app contexts. The most relevant one to A2HS is the splash screen displayed when the app icon on the Home screen is tapped and it first starts to load (this currently appears only when apps have been added to the Home screen by Chrome).
  • display: Specifies how the app should be displayed. To make it feel like a distinct app (and not just a web page), you should choose a value such as (no UI is shown at all) or (very similar, but system-level UI elements such as the status bar might be visible).fullscreenstandalone
  • icons: Specifies icons for the browser to use when representing the app in different places (such as on the task switcher, or more important, the Home screen). We've included only one in our demo.
  • name/short_name: These fields provide an app name to be displayed when representing the app in different places. provides the full app name, and provides a shortened name to be used when there is insufficient space to display the full name. You are advised to provide both if your app's name is particularly long.nameshort_name
  • start_url: Provides a path to the asset that should be loaded when the added-to-Home screen app is launched. Note that this has to be a relative URL pointing to the site index, relative to the url of the manifest. Also, be aware that Chrome requires this before it will display the install banner, whereas Firefox doesn't require it for showing the home-with-a-plus icon.

The manifest for our sample app looks like this:

{
  "background_color": "purple",
  "description": "Shows random fox pictures. Hey, at least it isn't cats.",
  "display": "fullscreen",
  "icons": [
    {
      "src": "icon/fox-icon.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ],
  "name": "Awesome fox pictures",
  "short_name": "Foxes",
  "start_url": "/pwa-examples/a2hs/index.html"
}

Appropriate icon

As shown in the above manifest listing, we are including a 192 x 192 px icon for use in our app. You can include more sizes if you want; Android will choose the most appropriate size for each different use case. You could also decide to include different types of icons so devices can use the best one they are able to (e.g., Chrome already supports the WebP format).

Note that the member in each icon's object specifies the icon's mimetype, so the browser can quickly read what type the icon is, and then ignore it and move to a different icon if it doesn't support it.type

In terms of how to design the icon, you should follow the same best practices you'd follow for any Android icon (see the Android icon design guidelines).

To finish setting up your manifest, you need to reference it from the HTML of your application's home page:

<link rel="manifest" href="manifest.webmanifest">

Browsers that support A2HS will know where to look for your manifest once this is in place.

What does A2HS not give you?

Bear in mind that when you add an app to your Home screen, it just makes the app easily accessible — it doesn't download the app's assets and data to your device and make the app available offline, or anything like that. To make your app work offline, you have to use the Service Worker API to handle storing the assets offline, and if required, Web storage or IndexedDB to store its data.

In our example app, we've just used a service worker to store all necessary files. The service worker is registered against the site with the final code block in the file. We then cache all the site's assets using the Cache API, and serve them from the cache instead of the network using the code in the sw.js file.index.js

A2HS on desktop

While originally intended to improve user experience on mobile OSes, there is movement to make PWAs installable on desktop platforms too.

Note: At the time of writing, the functionality described below was only supported in newer versions of Chrome — by default on Windows, and behind the flag on macOS.#enable-desktop-pwas

Adding an install button

To make our PWA installable on desktop, we first added a button to our document to allow users to do the installation — this isn't made available automatically on desktop apps, and the installation needs to be triggered by a user gesture:

<button class="add-button">Add to home screen</button>

We then gave it some simple styling:

.add-button {
  position: absolute;
  top: 1px;
  left: 1px;
}

JavaScript for handling the install

At the bottom of our index.js file, we added some JavaScript to handle the installation. First of all, we declare a variable (which we'll explain later on), get a reference to our install button, and set it to initially:deferredPromptdisplay: none

let deferredPrompt;
const addBtn = document.querySelector('.add-button');
addBtn.style.display = 'none';

We hide the button initially because the PWA will not be available for install until it follows the A2HS criteria. When this happens, supporting browsers will fire a event. We can then use a handler like the one below to handle the installation:beforeinstallprompt

window.addEventListener('beforeinstallprompt', (e) => {
  // Prevent Chrome 67 and earlier from automatically showing the prompt
  e.preventDefault();
  // Stash the event so it can be triggered later.
  deferredPrompt = e;
  // Update UI to notify the user they can add to home screen
  addBtn.style.display = 'block';

  addBtn.addEventListener('click', (e) => {
    // hide our user interface that shows our A2HS button
    addBtn.style.display = 'none';
    // Show the prompt
    deferredPrompt.prompt();
    // Wait for the user to respond to the prompt
    deferredPrompt.userChoice.then((choiceResult) => {
        if (choiceResult.outcome === 'accepted') {
          console.log('User accepted the A2HS prompt');
        } else {
          console.log('User dismissed the A2HS prompt');
        }
        deferredPrompt = null;
      });
  });
});

So here we:

  • Call Event.preventDefault() to stop Chrome 67 and earlier from calling the install prompt automatically (this behavior changed in Chrome 68).
  • Store the event object in the variable so it can be used later on to perform the actual installation.deferredPrompt
  • Set the button to so it appears in the UI for the user to click.display: block
  • Set a handler for the button.click

The click handler contains the following steps:

  • Hide the button again with — it is no longer needed once the app is installed.display: none
  • Use the method available on the event object (stored in ) to trigger showing the install prompt.prompt()beforeinstallpromptdeferredPrompt
  • Respond to the user's interaction with the prompt using the property, again available on the event object.userChoicebeforeinstallprompt
  • Set to null since it is no longer needed.deferredPrompt

So when the button is clicked, the install prompt appears.

If the user selects Install, the app is installed (available as standalone desktop app), and the Install button no longer shows (the event no longer fires if the app is already installed). When you open the app, it will appear in its own window:onbeforeinstallprompt

If the user selects Cancel, the state of the app goes back to how it was before the button was clicked.

Note: The code for this section was mostly taken from App install banners/Add to Home Screen by Pete LePage.

See also