How do I create an "Add to Home Screen" instruction page for iOS web apps

Question

I have a web app that can be easily added to the Home Screen of an iOS device, with a fancy icon.

However, I've noticed that some applications can load what seems like a completely separate page when viewed from Safari before the user adds it to the Home Screen.

This "special" page instructs the user on how to add it to the Home Screen, and when they do, it's a different page.

Notibly, http://darksky.net used to do this before they made an actual app. The Workflows app does this when you add a Workflow to your Home Screen. See screen shot below.

Am I not understanding things correctly, or is there a way to have a different page load when viewed from Safari and another one when it's added to the Home Screen?

Answer 1

You can detect if the site visitor is on an iOS device with some JavaScript then either show or hide the instructions based on a cookie:

1. Check if device is running iOS:

   if(!(/iPad|iPhone|iPod/.test(navigator.userAgent) && !window.MSStream)){ return false; }
   

2. Check if current view is already in webapp:

   if(window.navigator.standalone == true){ return false; }
   

3. Check if you have created a cookie for this user already:

   if(document.cookie.search("alreadAsked") >= 0){ return false; }
   

4. Prompt user by displaying an "Add to Homescreen" element on your page or redirecting to another page:

   document.getElementById("hiddenPrompt").style.display = 'inherit';
   

5. Store a cookie so you will not ask the user after they have added it. You can also store the cookie after the user clicks a "done" button instead so the user will be prompted until they add it to the home screen or click a "do not show this again" button:

   document.cookie = "alreadAsked=true; expires=Thu, 18 Dec 2099 12:00:00 UTC";
   

All together now, this function will run on page load:

// On page load
(function() {
  // Check if iOS
  if(!(/iPad|iPhone|iPod/.test(navigator.userAgent) && !window.MSStream)){ return false; }

  // Check if already in webapp
  if(window.navigator.standalone == true){ return false; }

  // Check if you already asked them to add to homescreen
  if(document.cookie.search("alreadAsked") >= 0){ return false; }

  // Ask user to add to homescreen
  document.getElementById("hiddenPrompt").style.display = 'inherit';
});

// After clicking a button to dismiss prompt
function hidePromptInFuture(){
  // Do not show prompt again
  document.cookie = "alreadAsked=true; expires=Thu, 18 Dec 2099 12:00:00 UTC";
}