• 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: TABlackmore
    • Posted on: 2011/01/23
    • At: 22:30

    Again some nice work from the webapp master.

    Reply
    • Author: Joop
    • Posted on: 2011/01/24
    • At: 11:30

    Very nice, Matteo. I tried it, but the close button gives an ‘A’ instead of an ‘x’. Any idea where to change this?
    Thank you.

    Reply
    • this is extremely weird. have you changed the file encoding? Anyway it’s on line 115.

      Reply
      • Author: lng
      • Posted on: 2011/03/07
      • At: 21:05

      Same problem. There is a A instead of a x. I changed it to iso-8859-1 before and now change back it to utf-8, but same.

      Reply
    • the file is not probably sent as UTF8 by the server

      Reply
      • Author: Kyle
      • Posted on: 2011/04/04
      • At: 23:41

      I’m having the same problem. and im unsure what should be on line 115. could you help me out a little

      Thanks,

      Reply
      • Author: Nate
      • Posted on: 2011/05/04
      • At: 04:13

      I had the same issue(I was actually using javascript files served by PHP, so it was likely an encoding issue), but I was able to avert the issue by simply replacing the x character with the unicode escape (\u00D7).

      Reply
      • Author: Beining
      • Posted on: 2011/05/22
      • At: 20:28

      Hi!
      The same occurs for me. I see that Nate found a solution, but where in the javascript can I change the x character with the unicode escape (\u00D7)? Its not on line 115 (as far as I can tell).

      I have added script on http://portada.no/butikk/index.html

      ps. Brilliant script btw!

      Reply
      • Please download the latest version. should fix your problem.

      • Author: Beining
      • Posted on: 2011/06/24
      • At: 21:58

      Thanks Matteo!
      Updated my site to utf-8 and the new script and now it works!
      Hurray! :)

      Reply
    • Author: Chris L
    • Posted on: 2011/01/24
    • At: 17:28

    I’ve seen several sites using a script like this, and sometimes it gets activated when I’m viewing the page inside a third-party app (Twitter, Instapaper, etc.) So of course it’s pointing to a button that doesn’t exist. I wonder if there is a solution for that.

    Reply
    • Author: Joop
    • Posted on: 2011/01/25
    • At: 09:48

    Thank you, Matteo. My file encoding was not set to utf-8.

    Reply
    • Author: Matthias
    • Posted on: 2011/01/25
    • At: 11:27

    One of the nicest “Add to home screen” messages I’ve seen. Thanks for sharing.

    Reply
    • Author: Rob
    • Posted on: 2011/01/26
    • At: 10:38

    Phenomenal! Really great code, just left a tip, thanks again!

    Reply
    • Author: Mark
    • Posted on: 2011/01/26
    • At: 17:53

    Wow great very nice.

    The localization is great.

    Would be great if it would be possible to localize a whole webapp with a XML file. I found this:

    http://www.samuelgarneau.com/lab/lang/

    But i do not know how to implement it so that the language detection choose the right language.

    Maybe that would be something for our “webapp master”

    Thanks

    Reply
    • Author: exliontamer
    • Posted on: 2011/01/28
    • At: 03:28

    hurray for Matteo, as his cube continues to spin, can’t to see what iScroll4 brings

    Reply
    • Author: Allen
    • Posted on: 2011/02/01
    • At: 16:29

    Excellent work! Thanks so much!

    Reply
  • I’m not much of a mobile developer, but from what I can see this effect looks money. I’ve also really enjoyed your blog. You should write about Web Dev more since you obviously have the touch.

    Reply
    • Author: Jon
    • Posted on: 2011/02/04
    • At: 19:48

    I’m in awe. Thank you.

    Reply
    • Author: heine
    • Posted on: 2011/02/07
    • At: 21:38

    That’s awesome!!! Thank you very much. Do you guys know something like this for Android phones?

    Reply
  • This is a great and very helpful addition to a website’s general user interaction — there’s just one little thing: Is there any chance to detect whether the web app was started from the home screen to then prevent the message to show up?

    Because after a user saved the website to his home screen it might become a bit annoying to stil see the message at every visit.

    Many thanks for your great effort and any further development.

    Reply
    • fullscreen mode is already detected. no message is displayed if in fullscreen mode (and apple-mobile-web-app-capable meta is active of course).

      Reply
    • Author: Jon
    • Posted on: 2011/02/11
    • At: 11:21

    I have this working fine on a couple of sites, but can’t seem to get it working with jQTouch – is this something you are aware of? Do I need to do anything differently? Many thanks.

    Reply
      • Author: Jon
      • Posted on: 2011/02/11
      • At: 11:37

      Bit more info…debugging tells me that all the required functions are called, even calls the start of the drop animation, just nothing being displayed. Seems jQTouch prevents the div from showing?? Not sure. Can anybody shed any light on this?

      Reply
    • maybe you need to higher the z-index? otherwise there must be some overlapping styles between my script and jqtouch.

      Reply
    • Author: Jon
    • Posted on: 2011/02/11
    • At: 12:32

    Thanks for reply. I added:

    div.style.zIndex=”999″;

    But no difference. I’ll check through for style conflicts as well – if I find anything I’ll let you know!

    Reply
      • Author: Jon
      • Posted on: 2011/02/11
      • At: 12:58

      No joy I’m afraid. Can’t see why it’s not displaying, zindex is set very high in css in any case, and no style conflicts from what I can see. Must be to do with jqtouch.js or a maybe a funny version of jquery.js ? Anyway, I’ll keep trying…

      Reply
    • Author: Jon
    • Posted on: 2011/02/11
    • At: 14:41

    Well, I got it working. With jQTouch, I couldn’t find a way to have the div append to the body as it was always rying to do so before the page load, due to the way jqt works.

    Anyway, I changed :

    document.body.appendChild(div);

    To:

    document.documentElement.appendChild(div);

    And it works fine! So looks like a workaround for those wishing to use this with jQTouch.

    Reply
    • thanks for sharing!

      Reply
        • Author: Pingpocket
        • Posted on: 2012/11/10
        • At: 17:10

        Thanks a lot Matteo for this really good script.
        Thanks Jon for the jQTouch fix.

      • Author: Gaia
      • Posted on: 2011/03/09
      • At: 10:26

      Where i have to change this string? in my jquery.js file? on my php document? can you post you entire code please? Help me :-))

      Reply
    • in the add2home.js script I presume. Search document.body.appendChild(div); and replace.

      Reply
      • Author: Keahi
      • Posted on: 2011/03/12
      • At: 12:26

      Thanks! This got it to work on iuI as well.

      Reply
    • Author: spataro
    • Posted on: 2011/02/24
    • At: 19:27

    Hey, good solution. Just to report you that on ipad – atomic browser, works emulating iphone, but as ipad doesn’t work.

    Using safari no problems.

    bye

    Reply
    • Author: Arvid
    • Posted on: 2011/03/06
    • At: 01:48

    Great work, i’m using this on my new webapp and it works flawless!

    Reply
    • Author: LekeFly
    • Posted on: 2011/03/10
    • At: 03:02

    Thanks alot. Anyway to have the bubble always appear in all browsers? ( easy to firebug and so on.. )

    Reply
    • Author: Always21
    • Posted on: 2011/03/10
    • At: 09:11

    a.w.e.s.o.m.e
    I’m very appreciated for your sharing!
    Thousands of thanks.. = )

    Reply
    • Author: DidmoDev
    • Posted on: 2011/03/15
    • At: 12:28

    This is a brilliant piece of code!
    I showed the results to my boss and he got seven kinds of excited and wants me to update the production code immediately.

    Reply
    • Author: Chris
    • Posted on: 2011/03/17
    • At: 14:07

    This is great. Added it to one of my projects!

    My first web app and it works great.

    Do you know why once I have added it to my homescreen it loads fine and I get the homepage, but when I click a link within my website it opens up in Safari?

    Do you know why it does this?

    Reply
    • Author: Monecchi
    • Posted on: 2011/03/21
    • At: 12:05

    On iPhone 4 it works great, but what happens to iPod Touch 4? :( I’ve testeted it on both devices and only iPhone 4 shows it.

    Reply
    • Author: Monecchi
    • Posted on: 2011/03/21
    • At: 19:32

    Well, Maybe that’s because I’ve implemented it on a dashcode web application ready project and something is messing up the code or even I’ve messed it up myself, I’ll double check it.

    Thanks for the info.

    Reply
    • Author: Monecchi
    • Posted on: 2011/03/21
    • At: 19:39

    Actually for me it is not showing up on the iPod Touch 4, even if I access the Demo link from the device it doesn’t work at all. Would it be because I’ve got it jailbroken? I mean this script checks the iOS version to show the correct icon etc. doesn’t it?

    Any help is welcome.

    Thanks in advance.

    Reply
    • can you post your:

      navigator.appVersion

      and

      navigator.platform

      Probably jailbroken devices use a non-default string.

      Thanks

      Reply
    • Author: Petteri
    • Posted on: 2011/03/29
    • At: 12:08

    Here´s a Finnish translation (there´s lot´s of iOS web-app productions going on in Finland right now):

    Asenna tämä web-ohjelma työpöydällesi: Paina [ ] -kuvaketta ja valitse “Lisää kotivalikkoon”.

    Reply
    • Thanks! I’ll add Finnish asap.

      Reply
    • Where should I place the %device name in your translation? (I guess the share icon is the [ ])

      Reply
    • Author: DidmoDev
    • Posted on: 2011/03/30
    • At: 14:58

    Does anyone else using this on the iPhone have a problem with the latest version of the i-nigma barcode reader?

    They’ve started opening the links in their own micro-browser, and I get a big fat NSURLErrorDomain error – 999 alert box over the loaded page, and the javascript execution breaks so the add2home bubble is never shown.

    Been trying in vain to catch and suppress that error…

    Reply
    • Author: Robert
    • Posted on: 2011/04/03
    • At: 11:17

    THANK YOU ! Another nice UI & very useful script. Strangely, the css-inline icon for the home screen button (the share icon, for iOS >=4.2) does not show up in my app on the iphone (https://grouptodo.com/) It does not show up in the XCode iphone/pad simulator either for me. Just shows a blank space there.

    I know it must be something I am doing wrong (since your demo works) but I cannot figure out what it is – can someone see it ?

    Reply
    • maybe an encoding error?

      Reply
      • Author: Robert
      • Posted on: 2011/04/06
      • At: 00:49

      Ah silly mistake on my side. Nothing to do with your code (css minifier was eating the base64)

      Reply
    • Author: Tinker Marz
    • Posted on: 2011/04/05
    • At: 07:30

    Does the script check if the website is already installed at the home screen? I ask, because the message is shown to me, even if I start the web app _from_ the home screen.

    Reply
    • Do you have a jailbroken iphone? If so please post your

      alert(navigator.appVersion)

      and

      alert(navigator.platform)

      thanks!

      Reply
    • Author: Macro Yau
    • Posted on: 2011/04/14
    • At: 14:07

    Nice work! I’m a developer from Hong Kong and I’ve translated the Traditional Chinese and Simplified Chinese message for you:

    Traditional Chinese (likely to be zh_TW): 您可以將此應用程式安裝到您的 %device 上。請按 %icon 然後點選加入主畫面螢幕
    Simplified Chinese (likely to be zh_CN): 您可以将此应用程式安装到您的 %device 上。请按 %icon 然后点选添加至主屏幕

    Keep up the good work.

    Reply
    • cool, thanks! I’ll update the script asap

      Reply
    • Author: di
    • Posted on: 2011/04/16
    • At: 08:17

    i love you man

    Reply
  • You did a great job there, thanks for the script! (Now by default in all my mobile websites).

    Reply
    • Author: BStewart
    • Posted on: 2011/05/06
    • At: 03:28

    Is there a way to programmatically open the balloon in a button’s onclick event?

    Reply
    • not without modifications to the code

      Reply
    • Author: ardin
    • Posted on: 2011/05/09
    • At: 00:03

    Anyone know if there’s a way to get this to work with a wordpress/wptouch site? I’ve tried adding the code to the actual wordpress header, and the wptouch head file, but to no avail.

    Reply
    • Author: cykane
    • Posted on: 2011/05/10
    • At: 09:40

    Sweet Feature, really good work!

    Greetz

    Reply
    • Author: EllSHEEN
    • Posted on: 2011/05/12
    • At: 10:14

    Is there anyway to stop the message coming up after someone has already ‘installed the web app’?

    Reply
    • it shouldn’t come up if the user added the app to the homescreen. If it does, it’s a bug and I’d need more info

      Reply
    • Author: Ardin
    • Posted on: 2011/05/14
    • At: 01:01

    Yeah, still comes up on mine after having been added to homescreen, running iOS 4.3.3 on an iPhone 4 from a wordpress site with wptouch for the mobile interface.

    Reply
    • Author: Steve
    • Posted on: 2011/05/16
    • At: 10:13

    Thank you for this nice bit of code, I’m using it on a mobile site I’ve made for the iPhone.

    Very nice ! Wish I could do stuff like that :-)

    Reply
    • Author: Donavan
    • Posted on: 2011/05/16
    • At: 18:15

    Thanx, this is a really nice ‘function’ for my webapp. But I have 1 problem: My apple-touch-icon won’t show in advanced mode :(

    Reply
    • Author: Tom McKearney
    • Posted on: 2011/05/18
    • At: 21:56

    This seems nice, but it keeps asking the question over and over. How do you tell when to stop asking?

    Reply
    • expire:1440
      asks it once per day.
      expire:10080
      only once per week.

      quote: “If you don’t want to show the message at each and every page load, you can set a timeframe in minutes. The message will be shown only one time inside that timeframe. Default: 0 (=always show).”

      Reply
    • Author: Dave
    • Posted on: 2011/05/19
    • At: 03:34

    Can’t get the icon to show.

    http://mobilewebsolutions.us/bywave/add.htm

    Any suggestions? Other than that, this is a sweeeet function. Very nice.

    Reply
    • Please update to the latest version. Also it is crucial that the JS file is served as UTF8. That should be default on recent webservers but you can force it by adding the following to your .htaccess:

      AddDefaultCharset utf-8
      AddCharset utf-8 .html .css .js .xml .json .rss

      If you don’t want to convert all your site to UTF8 you can serve just this script with the proper charset, like so:

      <Files “add2home.js”>
      AddDefaultCharset utf-8
      </Files>

      (Not tested but should work)

      If working with .htaccess is not possible, you may want to remove all languages but English from the script.

      Reply
      • Author: Dave
      • Posted on: 2011/05/21
      • At: 01:21

      I can’t. The download is .gz. I’d need a zip. The only version I can use is whatever you have setup for the demo. Can you update that to the latest version?

      Reply
    • you can get it from github… anyway I’ve updated the demo

      Reply
  • Hi
    I’m a newbie and really just want to create a basic mobile webkit site
    I’ve created this test subject to see If I’m any good but now want to add this to my site (Home Screen Bubble)
    Can anyone help ?
    http://82.45.130.37/atozcouriers/ftp/rb/kjh/001/testindex.html
    HTML File @-http://www.2shared.com/document/XdlY_yPp/index1.html?(Password 21)
    If any one could help that would be great
    Thanks keirjohnharry

    Reply
    • Author: bram
    • Posted on: 2011/05/24
    • At: 08:57

    Hi there,

    First of all, you make some cool stuff!
    What I noticed is that when you save the webpage on your homepage and you open it again, the website is an web app. How cool is that! But when you click on a link in that web app, you get redirected to Safari, so that’s kinda weird though.

    Reply
    • Author: bram
    • Posted on: 2011/05/24
    • At: 09:30

    Could you implent query.cookie.js (http://plugins.jquery.com/node/1386/release), so when somebody clicks on the ‘x’ (or ‘don’t show anymore’ link), the popup won’t show anymore when you refresh the website.

    Reply
    • the script uses localstorage that should be more stable than cookies. If you set the expire to 525600 you won’t see the message again for one year.

      Reply
  • Can anyone help me with my above issue ?
    I don’t even know how to put this into my website
    Please Help

    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>