Home Screen Shortcut
Updated: Mar 3, 2026
Copy for LLM
The Home Screen Shortcut feature lets you prompt players
This guide covers what home screen shortcuts are, why they matter, the SDK API, when and how to prompt players, platform support, and best practices.
What Is a Home Screen Shortcut?
A home screen shortcut is an icon on the player’s device home screen (or app drawer) that links directly to your Instant Game. It looks and behaves like a native app icon -- the player taps it, and your game opens immediately within the Facebook app or web browser.
From the player’s perspective, adding a shortcut makes your game feel like an installed app. It is always visible on their home screen, always one tap away, and always top of mind.
Why Home Screen Shortcuts Matter
The data on home screen shortcuts is compelling: players who add a home screen shortcut to an Instant Game show significantly higher retention rates compared to players who do not.
This makes sense for several reasons:
- Reduced friction: The #1 barrier to returning to a game is remembering it exists and navigating to it. A home screen icon eliminates both barriers.
- Constant visibility: Every time the player unlocks their phone, they see your game’s icon. This passive reminder keeps your game in their awareness.
- Habitual behavior: Tapping an icon on the home screen is a habitual action for mobile users. Once your game is part of their home screen, opening it becomes a habit.
- Perceived value: Adding a shortcut is a small commitment from the player. This act of investment makes them more likely to follow through and continue playing (a well-documented psychological principle).
If you do nothing else for retention, prompting for a home screen shortcut is one of the highest-impact actions you can take.
SDK API
The Instant Games SDK provides two methods for implementing home screen shortcuts.
Checking Availability
Before prompting the player, check whether the shortcut feature is available on their device using
FBInstant.canCreateShortcutAsync().async function checkShortcutAvailability() { try { const canCreate = await FBInstant.canCreateShortcutAsync(); if (canCreate) { console.log('Shortcut creation is available'); return true; } else { console.log('Shortcut creation is not available on this device'); return false; } } catch (error) { console.error('Failed to check shortcut availability:', error); return false; } }
canCreateShortcutAsync() returns false in the following situations:- The player has already added a shortcut for your game
- The device or platform does not support home screen shortcuts
- The player has dismissed the shortcut prompt too many times
- The feature is not available in the player’s region
Creating a Shortcut
If the shortcut is available, prompt the player to create it using
FBInstant.createShortcutAsync().async function promptShortcut() { try { const canCreate = await FBInstant.canCreateShortcutAsync(); if (canCreate) { await FBInstant.createShortcutAsync(); console.log('Shortcut created successfully!'); return true; } else { console.log('Shortcut not available'); return false; } } catch (error) { // Player declined or an error occurred console.log('Shortcut not created:', error); return false; } }
When
createShortcutAsync() is called, the platform displays a native prompt asking the player if they want to add the game to their home screen. If the player accepts, the shortcut is created. If they decline, the promise is rejected.When to Prompt
Timing is everything. A poorly timed shortcut prompt will be dismissed and may annoy the player. A well-timed prompt will feel like a helpful suggestion.
Do: Prompt After a Positive Gameplay Moment
The best time to ask for a shortcut is right after the player has had a positive experience:
- After completing their first few levels or rounds
- After achieving a new high score or personal best
- After receiving a reward or unlocking new content
- After winning a challenge or tournament match
- After a satisfying gameplay session
At these moments, the player is feeling good about your game and is most receptive to keeping it accessible.
Do: Explain the Benefit
Before showing the system prompt, briefly explain what adding a shortcut does and why it is useful:
async function showShortcutPromptWithContext() { const canCreate = await FBInstant.canCreateShortcutAsync(); if (!canCreate) { return; } // Show your own UI explaining the benefit first const userAccepted = await showCustomDialog({ title: 'Quick Access', message: 'Add this game to your home screen for instant access anytime. One tap to play!', confirmText: 'Add to Home Screen', cancelText: 'Maybe Later', }); if (userAccepted) { try { await FBInstant.createShortcutAsync(); showMessage('Game added to your home screen!'); } catch (error) { // Player declined the system prompt console.log('Player declined shortcut'); } } }
Do: Retry After Some Time
If the player declines the first time, do not give up forever. Wait several sessions (e.g., 5-10 play sessions) and try again. The player may not have been ready the first time but might be more invested later.
async function maybePromptShortcut() { const canCreate = await FBInstant.canCreateShortcutAsync(); if (!canCreate) { return; } // Check if we should prompt based on session count const data = await FBInstant.player.getDataAsync(['shortcutPromptCount', 'lastShortcutPromptSession']); const promptCount = data.shortcutPromptCount || 0; const lastPromptSession = data.lastShortcutPromptSession || 0; const currentSession = await getSessionNumber(); // Your own session tracking // Don't prompt more than 3 times total if (promptCount >= 3) { return; } // Wait at least 5 sessions between prompts if (currentSession - lastPromptSession < 5) { return; } try { await FBInstant.createShortcutAsync(); console.log('Shortcut created!'); } catch (error) { // Track the declined prompt await FBInstant.player.setDataAsync({ shortcutPromptCount: promptCount + 1, lastShortcutPromptSession: currentSession, }); } }
Do Not: Prompt Immediately on First Launch
The player has just started your game for the first time. They do not know if they like it yet. Asking them to add it to their home screen before they have played a single round is premature and will almost always be declined.
Do Not: Prompt During Active Gameplay
Never interrupt an active gameplay session with a shortcut prompt. The player is focused on playing, and any interruption feels disruptive. Wait for a natural pause (end of a round, return to the main menu).
Do Not: Prompt Repeatedly in a Single Session
If the player declines the prompt, do not ask again in the same session. Respect their decision and try again in a future session.
Platform Support
Android
Home screen shortcuts are well supported on Android devices running the Facebook app. When a player adds a shortcut:
- An icon appears on their home screen and in their app drawer
- Tapping the icon opens the Facebook app and launches the game directly
- The icon uses your game’s configured icon and name
Android is the primary platform for home screen shortcuts, and the feature works reliably across most Android devices.
iOS
iOS support for home screen shortcuts is more limited due to Apple’s platform restrictions:
- iOS does not allow apps to programmatically add icons to the home screen
- On iOS, the shortcut prompt may instead bookmark the game within the Facebook app or offer an alternative quick-access mechanism
- The availability of
canCreateShortcutAsync()may be more restricted on iOS
Because of these limitations,
canCreateShortcutAsync() may return false more often on iOS devices. Your game should handle this gracefully and not depend on the shortcut feature being available for all players.Web
On desktop web, the shortcut feature may add a browser bookmark or save the game for quick access within Facebook. The behavior varies by browser and platform.
Complete Code Example
Here is a complete example that handles the entire shortcut flow, including timing, tracking, and user feedback:
// Track whether we have already checked for shortcut in this session let shortcutCheckedThisSession = false; async function onLevelComplete(levelNumber, score) { // Show level completion screen showLevelCompleteScreen(levelNumber, score); // Check for shortcut prompt opportunity if (!shortcutCheckedThisSession && levelNumber >= 3) { shortcutCheckedThisSession = true; await maybePromptForShortcut(); } } async function maybePromptForShortcut() { // Check if shortcut creation is available const canCreate = await FBInstant.canCreateShortcutAsync(); if (!canCreate) { return; } // Check our own prompt history const playerData = await FBInstant.player.getDataAsync([ 'shortcutPromptCount', 'totalSessions', ]); const promptCount = playerData.shortcutPromptCount || 0; const totalSessions = playerData.totalSessions || 1; // Prompt at most 3 times, and only after enough sessions if (promptCount >= 3) { return; } // First prompt: after 3 levels in any session // Second prompt: after 10 total sessions // Third prompt: after 25 total sessions const promptThresholds = [0, 10, 25]; if (totalSessions < promptThresholds[promptCount]) { return; } // Show a brief delay so the player has time to see their score first await new Promise(resolve => setTimeout(resolve, 2000)); try { await FBInstant.createShortcutAsync(); // Player accepted showToast('Game added to your home screen! You can launch it anytime.'); } catch (error) { // Player declined -- record the attempt await FBInstant.player.setDataAsync({ shortcutPromptCount: promptCount + 1, }); } } // Track sessions for prompt timing async function onGameStart() { await FBInstant.initializeAsync(); const playerData = await FBInstant.player.getDataAsync(['totalSessions']); const totalSessions = (playerData.totalSessions || 0) + 1; await FBInstant.player.setDataAsync({ totalSessions: totalSessions, }); FBInstant.setLoadingProgress(100); await FBInstant.startGameAsync(); showMainMenu(); } onGameStart();
Best Practices
Treat It as a Retention Investment
The home screen shortcut is not a vanity metric -- it is a direct driver of retention. Track your shortcut creation rate as a key metric and invest in optimizing the prompt experience.
Make the Prompt Feel Natural
The best shortcut prompts feel like a natural part of the game experience, not an intrusive popup. Integrate the prompt into your game’s UI and flow rather than showing a generic dialog.
Track and Measure
Track the following metrics to understand the impact of your shortcut strategy:
- Prompt rate: What percentage of eligible players see the prompt?
- Acceptance rate: What percentage of prompted players accept?
- Retention lift: What is the retention difference between players who added a shortcut and those who did not?
Combine with Other Retention Features
The home screen shortcut works synergistically with other retention features. A player who has your game on their home screen AND receives timely notifications is more likely to return than a player who has only one or the other.
Respect Platform Limitations
Always check
canCreateShortcutAsync() before attempting to create a shortcut. Do not show shortcut-related UI or messaging if the feature is not available on the current device. The player should never see a broken or confusing experience.Next Steps
- Notifications Overview -- Set up notifications to complement your home screen presence.
- Leaderboards -- Give players a reason to come back after adding the shortcut.
- Building Social Games -- Design your game to maximize the retention benefits of home screen access.