• Posted on: Jan 23, 2011
  • Tag:
  • Reactions: 687

> Add to home screen

Add to home

Add To Homescreen (ATH) is a javascript widget that opens an overlaying message inviting the user to add the web site/application to the home screen. This was born mainly to support web-app-capable applications but extended to a more general purpose use case.

Support Development

Add To Homescreen is a free, open source javascript software. It is released under the MIT License which basically grants you complete freedom in usage for open source and commercial applications.

That being said the only way for me to subtract hours from my day work and keep implementing this script is through donations. If you find this widget useful and wish to support future development, please consider a donation.




Overview

The script opens an always-on-top message inviting the user to add the application to the home screen. This is currently supported on iOS and Mobile Chrome. While other devices have the ability to bookmark any website to the home screen, only iOS and Mobile Chrome have a straightforward way to do it. ATH would technically also work on Windows Phone (which has the equivalent Pin to Start option), but I’m not currently able to test it on that device. WinPhone support might be added in a future release if there will be enough interest.

ATH by default looks something like this

ath-preview

But appearance is customizable with plain old CSS.

The script is compatible with iOS 6+ and Chrome 31+. It would be possible to add iOS5 (and older) support, but considering the iOS7 penetration I decided to support the latest two releases only. If there’s really interest in older versions I might reintroduce <iOS5 support or you could use the previous version of ATH (which supports iOS3 and up).

Languages

The message changed in v3 so unfortunately all the languages supported in v2 are not available anymore. If you wish to help please send more translations!

Basic Usage

v3 API changed drastically (sorry about that) and it’s not a drop in replacement for v2. The good news is that v3 is aware of user sessions saved on previous ATH versions, so if the users have already seen the message, it won’t be displayed again.

The easiest way to use ATH is to link the script into your document HEAD and call the addToHomescreen() function as soon as possible. Eg:

<head>
<title>Add To Home</title>
...
<link rel="stylesheet" type="text/css" href="../../style/addtohomescreen.css">
<script src="../../src/addtohomescreen.js"></script>
<script>
addToHomescreen();
</script>
</head>

That’s all you need. ATH automatically hooks to the onload event, checks device compatibility, detects if the app is already in full screen mode and eventually pops up the message.

It is not strictly needed to place the script in the document HEAD (you can also place it at the end of your BODY), but ATH makes a series of checks that are better done sooner than later.

Options

ATH accepts one option parameter to customize the script behavior.

To change the start up delay for example you could use the startDelay option.

addToHomescreen({
   startDelay: 5
});

This would delay 5 seconds before showing the message.

Below the most common options.

  • modal: prevents further actions on the website until the message is closed.
  • mandatory: the website is not accessible until the user adds the application to the homescreen. This is useful mainly for web-app-capable applications that need full screen viewing to be accessed (eg: games).
  • skipFirstVisit: setting this to true prevents the message to appear the first time the user visits your website. It is highly recommended to enable this option!
  • startDelay: seconds to wait from page load before showing the message. Default: 1.
  • lifespan: seconds to wait before automatically close the message. Default: 15 (set to 0 to disable automatic removal).
  • displayPace: minutes before the message is shown again. By default it’s set to 1440, meaning that we will be showing the message only once per day.
  • maxDisplayCount: absolute maxium number of times the call out will be shown. (0 = no limit).
  • icon: display the touch icon in the pop up message. Default: true
  • message: you can provide your custom message if you don’t like the default.
  • onShow: custom function executed when the message is shown.
  • onAdd: custom function executed when the application is added to the homescreen. Please note that this is a guesstimate (see below).
  • detectHomescreen: ATH tries to detect the homescreen. Supported values are: false, true (=’hash’), ‘hash’, ‘queryString’, ‘smartURL’ (see below).
  • autostart: the message is not shown automatically and you have to trigger it programmatically.

Detect the homescreen

There’s no native event we could hook to to know when a user actually adds the page to the homescreen. That’s also the reason why this script has become so complicated despite the apparent simple task it has to accomplish.

ATH development started when Apple introduced the apple-mobile-web-app-capable meta tag and stand alone mode with it. When the webapp is in stand alone mode the window.navigator.standalone property is set to true and that’s the only 100% safe way to know if the app has been added to the homescreen… With some caveats (of course).

// set a web app capable website
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="mobile-web-app-capable" content="yes">

Standalone mode is meant for web applications, not “standard” web sites. The webapp has to be designed with standalone mode in mind, for example links inside your fullscreen app will open in a new browser window hence your app navigation has to be handled with JS.

Also, as of this writing Chrome –despite support for mobile-web-app-capable– doesn’t fill the window.navigator.standalone property, making it an unreliable way to detect if the app has been added.

So, how can we detect if the app has been actually added to the home screen? ATH tries its best to help you in this hard task and the followings are your options.

  • Show the callout only once per user. This is the best, safest and most polite solution of all. Set the maxDisplayCount to 1 and the user will be presented with the nasty callout only one time, smartly circumventing the problem.
  • Build a standalone application. When possible try to use apple-mobile-web-app-capable.
  • Add a special token in the URL and have the user bookmark the tokenized address. ATH supports hash, query string or smart url tokens. Continue reading for details.

I strongly suggest to go with the first option and show the callout only once. That’s the safest solution, but if you want to be more aggressive you can take the “token” route.

First of all you have to choose where to place the token. ATH offers three options:

  • hash: http://www.example.com/#ath
  • query string: http://www.example.com/?ath=
  • smart url: http://www.example.com/ath/

As soon as the page is loaded ATH adds the token to the page URL (no worries, no reload will happen as we use history.replaceState). If the user adds the page to the homescreen the actual URL that will be saved contains the token. If the page already contains the token before ATH could add it, it means that (most likely) the page has been added to the homescreen.

Bear in mind that this is a guesstimate, there are some exceptions but the good news is that it should be pretty rare to have false positive, ie: it should never happen to see the popup after the app has been added. Instead it may happen to have ATH think that the app has been added even if it hasn’t.

Be careful when using the detectHomescreen option since it may interfere with your application especially if you already use #hash or history.replaceState for your navigation.

Optimal configuration

Do not annoy your users with frequent callouts the suggested setup is to show the message only once, the second time the user visits your website.

addToHomescreen({
   skipFirstVisit: true,
   maxDisplayCount: 1
});

The above config skips the first time the user comes to your site, so she has time to look around freely. The next time she will be greeted by the cheerful balloon and from that moment on she won’t be bothered again.

Debug mode

ATH v3 also introduces debug mode. By setting debug: true some of the preliminary checks are skipped and the message is shown on desktop browsers and unsupported devices as well.

You also have the addToHomescreen.removeSession() function in your tool belt, which clears the current session. This is very useful when testing various options and the callout seems not to be willing to show up again. This is common because ATH is very conservative, to avoid showing the message by mistake it tries to show it the less as possible.

Open the pop up programmatically

Of course you can bypass the automatic triggering and open the call out programmatically. To do so you have to set the autostart: false option.

var addtohome = addToHomescreen({
   autostart: false
});
addtohome.show();

addToHomescreen() it’s a kind of singleton and returns the instance to the real AddToHomescreen class. From there you have access to the show() method. Note that no checks are performed to verify if the DOM is ready, if you show the message programmatically that’s up to you.

show() also supports one boolean option. If you pass true the callout is shown no matter what overriding most of the preliminary tests.

localStorage variable name

The user session is stored in a localStorage variable called org.cubiq.addtohome by default. localStorage is domain based, so if you have multiple applications on the same domain ATH can’t understand which one you actually added to the homescreen.

You can have multiple instances of ATH on the same domain by setting a different appID for each installation. Eg:

addToHomescreen({
   appID: 'org.cubiq.myCoolApp'
});

IMPORTANT: once set do not change the appID! If you change the appID all users will see the callout again regardless if they already added the application to the home screen or not. Only exception is for standalone applications. They would keep working correctly anyway.

apple-mobile-web-app-title

From iOS6 you have a handy meta tag called apple-mobile-web-app-title that holds the name that will be displayed on the homescreen, otherwise the page title will be used. Since the app name is limited to 11 characters you may want to take advantage of this feature.

/Share the joy

/Reactions

    • Author: Jos Gerrits
    • Posted on: 2013/01/23
    • At: 09:42

    Hey Matteo,

    Great plugin! The only problem i have is one which happens on just one iphone 4s. I have no idea why but on my other iphone 4s is does work.

    It’s the same problem multiple other have been experiencing with the close button. Mine simply does not close at all. Not even with the latest version where you made the whole bubble a close listener.

    I’m using Sencha Touch 2. Thanks!

    Jos.

    Reply
    • Sencha is probably the culprit. try to raise the z-index of the balloon from the CSS.

      Reply
    • Author: Raffaele
    • Posted on: 2013/01/23
    • At: 17:12

    Is possible to check if the user added the shortcut on the home so not showing again the popup?

    And the last thing, if set expire= 60 it will show the popup again after 60 minutes right?

    Thank you
    Respect

    Reply
    • 1. please check the last two paragraphs of the documentation

      2. precisely

      Reply
    • Author: Willem
    • Posted on: 2013/01/23
    • At: 18:01

    Is it also possible to show this popup only on the homepage?

    Reply
    • the script should be included only on the pages you want the popup to show up. if you can’t do it server side you could check window.localtion.href

      Reply
      • Hi Matteo, could you elaborate on the use of the window.localtion.href command to do this. I have WordPress sites and have placed the code in to the header.php file however I am getting the pop-up on every page and would like to just have it appear on the home screen or just appear the once when you visit the site no on every subsequent page clicked after landing. I tried adding the code however this does not appear to work in the WordPress environment. Thanks for you support and Awesome code! :)
        Danny

    • Author: rich
    • Posted on: 2013/01/24
    • At: 14:39

    It seems like a great plugin except that I experience this strange behaviour.

    On my iphone or ipad it drops down and is only visible for like 50% of the opacity and then it dissapears again. I did use the example code from the download.
    Do you have any idea?

    Reply
    • Author: hehe13
    • Posted on: 2013/01/24
    • At: 21:40

    hi, im jsut starting html and css.. but ive been using ipod touch for almost a year.. i found your tweak to be very useful… im fond of making html based shortcut for my apps / tools on my work.. ive got tons of tools, so i decided to create a html page and link all .exe files + my notes + spiel + email updates + notepad on a single page.. if its posible, you could make / teach me/us to create a shortcut for toggles on the settings app..

    Reply
    • Author: jazeppi
    • Posted on: 2013/01/25
    • At: 06:26

    Ok, so I have a wordpress site. I went into my ftp and added a folder named iDevices into my wp-content folder. I then added your add2home.sss and add2home.js files into the folder. I then went to appearance/editor, header. php and entered the code:
    I then tried to open my website on iPad and iPhone, but there is absolutely no add to home screen button appearing. Is there another step that I’m missing? Any help would be greatly appreciated!

    Reply
    • Author: Issy
    • Posted on: 2013/01/25
    • At: 19:46

    Thanks for the tutorial!!!
    Everything works great!
    So, you mentioned a different way of preventing the balloon from showing. I don’t have the “web app capability”, I include the script to the home page of my website. My problem is that I’m new in the matter and I don’t really know how to check for a special url hash. Could you please show me an example? or a different option?
    In advance,
    Thanks very much.

    Reply
    • Author: Al
    • Posted on: 2013/01/29
    • At: 22:45

    Very nice but it seems like once I am using this if I add my web app to home screen and then open my web app from that home screen icon it no longer has the address bar in safari. Also in my page I added to homescreen I have redirects with rel=”external” and new instances of safari are then opened. Anyway to keep the default behavior when I added to home screen before using your plug in?

    Reply
    • Author: Thomas
    • Posted on: 2013/01/31
    • At: 08:54

    Thank you so much for this script! I do have one problem though.. When I scan a QR code the link will not open directly in Safari, but inside the QR application – and then you don’t get this popup message..

    Is there a way to solve this?
    (I also tried scanning your QR code, but this is also opening inside the QR app, and there is no popup..)

    Reply
    • Author: RJ
    • Posted on: 2013/02/01
    • At: 21:41

    I had to change the event listener to touchstart – the click event did not work on my iphone or ipad to close the balloon.

    if ( options.closeButton ) balloon.addEventListener(‘touchstart’, clicked, false);

    Reply
    • do you use any framework? such as jquery mobile?

      Reply
        • Author: RJ
        • Posted on: 2013/02/12
        • At: 12:56

        We are using Sencha Touch SDK.

    • Author: Johnny
    • Posted on: 2013/02/03
    • At: 08:27

    Hello!

    This is an AWESOME article. Thanks!!!

    The only problem I have is that when I set touchIcon:true, it shows “null” in place of the icon.

    The head tag has

    Am I doing something wrong?

    Reply
    • would you please post a demo page? does it do the same with the included examples?

      Reply
    • You should ALWAYS set the icon size in the apple-touch-icon link tag. Eg:

      <link rel="apple-touch-icon" href="path/to/img.png" sizes="144x144" />

      Reply
    • Author: Gary Smith
    • Posted on: 2013/02/03
    • At: 18:21

    Where does the script reside? In the root? or? Am I missing something? I can open the read-me.

    Thanks

    gs

    Reply
    • Author: Peter Mc
    • Posted on: 2013/02/03
    • At: 22:43

    I use Rapidweaver and have added the Standard Usage code to the head and the addtohome.css and add2home.js to my htdocs folder, but nothing happens, any idea what I am doing wrong?

    Reply
    • Author: Ruben
    • Posted on: 2013/02/06
    • At: 11:30

    Hi,

    I miss something like a developer-Mode to test and style the bubble in desktop-browser. Something like Desktop=true as a parameter. Mayer there is a Otter solution i dont recognize!?

    Thanks for this Great Script.

    Gereinigt from Germany
    Ruben

    Reply
    • yes, that has been already asked I believe. I may add something like that in a future release.

      Reply
        • Author: Ruben
        • Posted on: 2013/02/07
        • At: 09:15

        Thanks for the fast answer. Iam Looking forward for that Feature!
        By the Way i hate autocorrect ;)

    • Author: Lamson
    • Posted on: 2013/02/07
    • At: 09:31

    First of all as everybody else, I want to thank you and congratulate you for your great code.
    I added the meta code you provided above for “apple-mobile-web-app-capable” but it keeps showing the popup. Have you any suggestion ?

    Thanks a lot !

    Reply
    • Author: Andreas
    • Posted on: 2013/02/19
    • At: 08:34

    Hi,

    This works great when I go directly to my mobile website URL. However when I visit my regular homepage URL and then is being forwarded to the mobile website url, then this script is not showing up.

    Any ideas?

    Reply
    • Author: thanks for the plugin
    • Posted on: 2013/02/20
    • At: 17:08

    Thanks for the plugin!
    Is great, but I found that it doesn’t work when private browsing is on, I added this bit of code to bypass the sessionStorage part. It could explain why the last commenter’s 2 phones are different..
    function clicked () {
    var canstore = true;
    var testKey = ‘qeTest’, storage = window.sessionStorage;
    try {
    // Try and catch quota exceeded errors
    storage.setItem(testKey, ’1′);
    storage.removeItem(testKey);
    } catch (error) {
    if (error.code === DOMException.QUOTA_EXCEEDED_ERR && storage.length === 0)
    //alert(‘Hello, private browser.’);
    canstore = true;
    else throw error;
    }
    if (canstore = false){
    isSessionActive = true;
    sessionStorage.setItem(‘addToHomeSession’, ’1′);
    }
    close();
    }

    That was taken from here:
    http://m.cg/post/13095478393/detect-private-browsing-mode-in-mobile-safari-on-ios5

    Thanks again

    Reply
    • Author: Debbie
    • Posted on: 2013/02/23
    • At: 16:52

    Hi

    Do you have set instructions on how to add this or a tutorial? Is it suited for wordpress?

    Thank you

    Reply
    • Author: Florian Schär
    • Posted on: 2013/02/26
    • At: 17:21

    After adding to home screen and then opening the status bar on the bottom is missing. Is there a possibility to publish this again?

    Reply
    • Author: IVan
    • Posted on: 2013/02/26
    • At: 17:49

    Hi , thank you for the great plugin.
    I had a small question:
    Can you somehow trace how many people added the app to their home screen?
    Track how many click throughout Google analitics or something?

    Thank you

    Reply
    • Author: Florian
    • Posted on: 2013/03/01
    • At: 09:36

    One more question:
    Opening the site from the installed home screen there is on iphone 5 devices free space at the top and the bottom. Is there a solution to show it over the whole screen?

    Reply
    • Author: mike
    • Posted on: 2013/03/05
    • At: 22:20

    Good job!
    Why don’t expand it to Android and Blackberry platforms?

    Reply
    • Author: Dirk
    • Posted on: 2013/03/10
    • At: 23:46

    Very nice!! And working on the iPad but not on the iphone (4). Like many others I am not able to close the message box (tested it on the demo site, before installing on my own site)

    Can make a movie if you want to.

    For the rest; great work!

    Reply
    • need more info about the iphone (OS version). post a video if you can.

      Reply
        • Author: Dirk
        • Posted on: 2013/03/13
        • At: 22:39

        Hi, the iphone is an iphone 4 with IOS 6.1 installed.

        The video of the iphone behaviour is on youtube:

        http://youtu.be/U072ES4tOBE

        With an ipad I visited the same demo page and it works there:
        http://youtu.be/RNincYO5osU

        It’s the same some of the others are saying in previous comments. Doesn’t matter where you tab the message will not close. Doing this on the iPad it works like expected. If you need me to test anything just let me know.

      • could you try to shutdown the iphone and retry?

        • Author: Dirk
        • Posted on: 2013/03/20
        • At: 11:12

        Now it works!

      • I’m having the same problem but restarting my iPhone did not fix it. I tap the Close Button but the balloon will not close.

        iPhone 4s
        iOS 6.1.3 (10B329)

        Thanks.

      • would you try to hard reboot your iPhone?

      • Sorry. Forgot some info. A co-worker has an iPhone 5 with the same version of iOS. The Close Button works correctly on it.

      • I tried the hard reboot. It didn’t work. I went to your demo and the Close Button does not work their either. The only things I changed in the script were the normally editable “settings”. I didn’t change any code outside of those.

        I can’t remember what line this was on but there is a event handler for the Close Button. Someone said to change it from ‘click’ to ‘touchstart’. That didn’t work either. I changed it back to ‘click’.

        I also removed the other script from the page to see if there was a conflict. The Close Button still didn’t work.

    • Author: Mike
    • Posted on: 2013/03/11
    • At: 21:47

    “remember to add the apple-mobile-web-app-capable meta to your page head”

    How can I know when to add this tag?

    Reply
    • Author: Clay
    • Posted on: 2013/03/11
    • At: 21:57

    Will this script behave the same on the Blackberry or Android OS? If Not are there codes or modifications that will do the same thing?

    Reply
    • Author: Holly
    • Posted on: 2013/03/15
    • At: 03:53

    Ive installed the .js file, and the .css file into the site, added the script in my wordpress website and its not working, can someone post a tutorial on how it works in wordpress???

    Reply
      • Author: Holly
      • Posted on: 2013/03/15
      • At: 17:52

      I figured out, the script that i install on my header needs to have the path to where the url is at needs to be set. so it can find where the .css and .js file is at. and now that i did that it works great!

      Reply

/Leave a reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>