Include icon when Add to Home Screen from Android Chrome
Categories:
Ensuring Your Web App Icon Appears When 'Add to Home Screen' on Android Chrome
Learn how to properly configure your web manifest and HTML to ensure your Progressive Web App (PWA) icon is correctly displayed when users add it to their home screen from Android Chrome.
The 'Add to Home Screen' (A2HS) feature in Android Chrome allows users to install Progressive Web Apps (PWAs) directly to their device's home screen, providing an app-like experience. A crucial part of this experience is a well-designed and correctly displayed icon. However, developers often encounter issues where the default Chrome icon or a screenshot of the site is used instead of their custom icon. This article will guide you through the necessary steps to ensure your PWA icon is always displayed correctly.
Understanding the Web App Manifest
The Web App Manifest is a simple JSON file that tells the browser about your web application and how it should behave when 'installed' on the user's mobile device or desktop. It's essential for providing the necessary metadata, including the application's name, theme colors, and, most importantly, the icons that will be used for the home screen.
{
"name": "My Awesome PWA",
"short_name": "Awesome PWA",
"description": "A description of my awesome PWA.",
"start_url": ".",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#000000",
"icons": [
{
"src": "/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
},
{
"src": "/icons/maskable_icon.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any maskable"
}
]
}
Example of a manifest.json file with multiple icon sizes and a maskable icon.
Linking the Manifest in Your HTML
Once your manifest.json file is created, you need to link it within your HTML document's <head> section. This tells the browser where to find the manifest file and apply its configurations to your web app.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My PWA</title>
<link rel="manifest" href="/manifest.json">
<link rel="apple-touch-icon" href="/icons/icon-192x192.png">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<meta name="apple-mobile-web-app-title" content="Awesome PWA">
</head>
<body>
<h1>Welcome to My PWA!</h1>
</body>
</html>
Linking the manifest file and including Apple-specific meta tags for broader compatibility.
href path to your manifest.json is correct and accessible. A broken link will prevent Chrome from recognizing your PWA's configuration, leading to default icon behavior.The Importance of Maskable Icons
Modern Android devices use adaptive icons, which means they can display various shapes (circles, squares, squircle, etc.) for app icons. A 'maskable icon' is designed to look good inside these varying shapes. If you don't provide a maskable icon, Android might crop your icon or display it with a white background, which can look unprofessional. The purpose: "any maskable" field in your manifest's icon definition is crucial here.
Understanding the safe zone for maskable icons to ensure proper display across different Android shapes.
Verifying Your PWA Configuration
After setting up your manifest and linking it, it's vital to verify that Chrome is correctly detecting your PWA and its icons. The Lighthouse audit tool within Chrome DevTools is an excellent resource for this. It provides a 'Progressive Web App' category that checks for manifest presence, icon sizes, and other PWA best practices.
1. Step 1
Open your PWA in Google Chrome on your desktop.
2. Step 2
Open Chrome DevTools (F12 or Ctrl+Shift+I).
3. Step 3
Navigate to the Lighthouse tab.
4. Step 4
Select the Progressive Web App category and click Analyze page load.
5. Step 5
Review the PWA audit results, specifically looking for checks related to 'Manifest has a start_url', 'Manifest specifies at least one icon with a size of 192px', and 'Manifest has maskable icon if applicable'.
Application tab in Chrome DevTools, then select Manifest on the left sidebar. This will display your parsed manifest file and show any warnings or errors related to its content.