Install Prompts and Home Screen Icons

Step 1: Capture the beforeinstallprompt Event

When Chrome, Edge, or Samsung Internet determine that a user is eligible to install your PWA (based on meeting the manifest and service worker requirements and engagement heuristics), the browser fires a beforeinstallprompt event on the window. By default, the browser shows a small banner or mini-infobar prompting installation. For games, this default prompt appears at the wrong time and looks generic, so you want to intercept it.

Add an event listener for beforeinstallprompt early in your game's initialization code. When the event fires, call event.preventDefault() to suppress the default browser prompt, then store the event object in a variable. This captured event has a prompt() method that you can call later at the right moment to trigger the system install dialog. The event can only be used once, so choose your moment wisely.

If the beforeinstallprompt event has not fired, the player either does not meet the browser's engagement criteria, has already installed the app, or is using a browser that does not support the API (Firefox, Safari). Check the display-mode media query to detect if the game is already running as an installed PWA, and hide the install prompt entirely for those users.

Step 2: Design the In-Game Install Prompt

The custom install prompt should feel like part of your game, not like a browser notification. Use your game's visual style, colors, and typography. Frame the value proposition in terms the player cares about: "Play offline anytime," "Launch instantly from your home screen," or "Never lose your progress." Avoid technical language like "Install this Progressive Web App."

The prompt should include two clear actions: an "Install" button that calls deferredPrompt.prompt() and triggers the system dialog, and a "Not now" button that dismisses the prompt. Do not use a simple X button for dismissal. A labeled "Not now" button is less hostile and leaves the door open for showing the prompt again in a future session.

After the player taps "Install" and the system dialog appears, wait for the userChoice promise to resolve. It returns an object with an outcome property that is either "accepted" or "dismissed". If the player accepted, update your UI to remove the install prompt and optionally show a brief "Thanks for installing" confirmation. If dismissed, set a flag in localStorage to avoid showing the prompt again too soon.

Position the prompt where it is visible without blocking gameplay. A banner at the top or bottom of the screen works for menu states. During active gameplay, wait for a natural pause like a level complete screen, a game over screen, or a pause menu. Never overlay the install prompt during active gameplay, players will dismiss it reflexively and develop negative associations with the interruption.

Step 3: Time the Prompt for Maximum Conversion

Showing the install prompt on the first visit almost never works. The player has not experienced the game yet, so "install this" has no value to them. Research across PWA case studies consistently shows that delayed prompts convert 3-5x better than immediate prompts.

Effective triggers for games include: completing the first level or tutorial (the player has engaged and wants more), achieving a new high score (emotional high, positive association), returning for a second session (demonstrates repeated interest), or reaching a milestone like 5 minutes of play time (proves genuine engagement). Track these events in your game logic and show the install prompt when one of them fires, but only if the beforeinstallprompt event has been captured.

Implement a cooldown. If the player dismisses the prompt, do not show it again for at least 7 days. Store the dismissal timestamp in localStorage and check it before displaying the prompt. After 2-3 dismissals total, stop showing it entirely for that browser. Persistent prompting creates a negative experience that drives players away.

A/B testing prompt timing can reveal what works best for your specific game. Track installation rates (installed / prompt shown) for different trigger points. Some games find that post-tutorial works best, others see higher conversion on second-session return visits. Let your data guide the decision.

Step 4: Create Icons and Splash Screen Assets

Home screen icons are the player's permanent visual connection to your game. They should be instantly recognizable at small sizes (around 48x48 CSS pixels on most devices) and represent the game's identity without text. Use your game's main character, logo mark, or a distinctive symbol. Avoid text in icons because it becomes illegible at small sizes, and the game's name already appears as a label beneath the icon.

The manifest requires icons at multiple sizes. At minimum, provide 192x192 and 512x512 pixel PNG files. The 192px icon is used on the home screen and in the app list, while the 512px version appears on splash screens and in app management interfaces. For comprehensive coverage across all devices, also include 48x48, 72x72, 96x96, 144x144, and 384x384 sizes. Tools like PWA Asset Generator, Maskable.app, or RealFaviconGenerator can create all required sizes from a single high-resolution source.

Design icons with the maskable safe zone in mind. Android applies adaptive icon shapes (circle, rounded square, squircle) that crop the edges of your icon. The safe zone is the inner 80% of the icon area. Keep all important visual elements within this zone to avoid clipping. In your manifest, include a maskable icon variant alongside the standard icons by setting "purpose": "maskable" on the appropriate size. Include a separate icon with "purpose": "any" for platforms that display icons without masking.

The splash screen appears briefly when the installed game launches, bridging the gap between the tap and the first frame of gameplay. Chrome generates the splash screen automatically from the manifest's name, background_color, and the 512x512 icon. Choose a background_color that matches your game's loading screen to create a seamless transition. Dark backgrounds work well for most games and feel more polished than the default white.

Step 5: Handle iOS Installation Separately

Safari on iOS does not support the beforeinstallprompt event. There is no programmatic way to trigger an install dialog on Apple devices. Instead, players must manually add the game to their home screen through Safari's Share menu: tap the Share icon (the square with an upward arrow), scroll down, and tap "Add to Home Screen."

Detect iOS by checking the user agent for "iPhone" or "iPad" combined with the absence of the beforeinstallprompt event. When iOS is detected, show a custom instruction overlay that visually walks the player through the manual install steps. Include annotated screenshots or simple illustrations showing the Share button location and the "Add to Home Screen" option. Make the overlay dismissible and, like the Android prompt, time it after the player has engaged with the game.

Use the apple-touch-icon link tag in your HTML head to provide icons for iOS. Safari ignores the manifest's icon definitions and uses the apple-touch-icon instead. Provide a 180x180 pixel PNG for iPhones and a 167x167 pixel PNG for iPads. These icons should not have rounded corners or gloss effects, as iOS applies its own mask.

The apple-mobile-web-app-capable meta tag must be set to "yes" for the game to run in standalone mode (without Safari's browser chrome) when launched from the home screen. Without this tag, the game opens in a regular Safari tab even when launched from the home screen icon, which defeats the purpose of installation.

Step 6: Track Installation Metrics

Listen for the appinstalled event on the window object. This fires when the player completes the installation, regardless of whether it was triggered by your custom prompt or the browser's default UI. Log this event to your analytics platform to track installation rates over time.

Calculate your installation funnel: what percentage of visitors see the install prompt, what percentage of those tap "Install," and what percentage complete the installation. Compare these metrics across prompt triggers (post-tutorial vs. post-high-score vs. second-visit) to optimize your strategy.

Track post-install retention separately from browser retention. Installed users typically show 2-4x higher 7-day retention. If you see this pattern in your data, it validates the investment in optimizing the install flow and justifies spending time on icon design, prompt timing, and iOS instructions.

The display-mode: standalone media query lets you detect whether the current session is running as an installed PWA or in a browser tab. Use this to log separate analytics sessions for installed vs. browser users, giving you clean data on the behavioral differences between the two groups.