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

> Add to home screen

Add to home

I found that many iPhone and iPad users don’t know that they can add their favorite web sites to the Home Screen and interact with them like standard native applications. This script helps them to discover this great feature and suggests the steps needed to add your web app to the dashboard.


Project info

Name: Add to Home screen
Last code update: 2013.01.18 – v2.0.5
Device compatibility: iPhone/Ipod touch >=3.1.1, iPad >=3.2.
QR Code opens demo page.

Support development

If this script saved your day and you wish to support future developments you may consider sending some funds via PayPal or Flattr.





Overview

The script places a floating balloon inviting the user to add your application to the home screen. Version 2 of the script takes advantage of iOS5 native fixed elements positioning and gracefully degrades to a javascript only version on iOS4.

The default message looks like this:

The code is compatible with iPhone/iPod touch, iPhone4 and iPad. On older devices the “add” icon is a “+” while on iOS 4.2 it has been replaced with . The script detects the OS version and displays the appropriate icon.

The message appears after 2 seconds (customizable) from page load, and is destroyed after 15 seconds (also customizable). The balloon enters and exits the screen with a quick configurable animation: drop from top, bubble from bottom or fade in/out.

The balloon can be dismissed any time by tapping the small “x” icon.

The script also checks the user’s locale and shows the message in an appropriate language. So far the following languages are supported:

  • Catalan
  • Chinese (Traditional and Simplified)
  • Danish
  • Dutch
  • English
  • Finnish
  • French
  • German
  • Greek
  • Hebrew
  • Hungarian
  • Italian
  • Japanese
  • Korean
  • Norwegian
  • Polish
  • Portuguese
  • Russian
  • Spanish
  • Swedish
  • Thai
  • Turkish

Please help me localize the script in more languages.

Locale can be forced, so you can use only English if so desired.

Standard usage

All you need to do for the magic to happen is to add the following inside your page HEAD:

<link rel="stylesheet" href="path/to/add2home.css">
<script type="application/javascript" src="path/to/add2home.js"></script>

That’s it. The code checks the user’s device, OS version, standalone compatibility, etc. If the user is eligible, the screen will be gladden with the cheerful balloon.

Advanced features

You can customize the script behaviors by setting the addToHomeConfig global variable *before* the add2home.js script is included into the page. Let me stress on this. The variable must be globally accessible and must be defined before the script is included inside the page.

Here’s a simple example:

<script type="text/javascript">
var addToHomeConfig = {
	animationIn: 'bubble',
	animationOut: 'drop',
	lifespan:10000,
	expire:2,
	touchIcon:true,
	message:'This is a custom message. Your device is an <strong>%device</strong>. The action icon is `%icon`.'
};
</script>
<script type="application/javascript" src="js/add2home.js"></script>

The popup appears with a bubble effect and is dismissed with a drop animation. It stays on screen for 10 seconds, it is shown only once every 2 minutes, it shows the apple-touch-icon, and changes the default text with a custom one. This is the end result:

Autostart

The script automatically starts on page load. You can prevent this behavior by passing the autostart:false option. You can later show the balloon calling the addToHome.show() public method.

You can also override all the compatibility checks and always show the popup by calling addToHome.show(true). (Not suggested!).

Returning visitors

V2.0 adds the returningVisitor option. This is a very important feature that I highly encourage you to use (ie: set it to true). What it does is to show the message to returning visitors only. The first time a user accesses your site the message is not shown. If the user comes back within a 28 days timeframe, the message is finally presented.

I believe this is very important for usability. When I end up on a new site I just want to look around and there is a very small chance that I will really come back to that site again. But if I come back a second time there’s a good chance that I’ll return a third and a forth.

Showing the message the very first time a user visits your site could be self-defeating and may just irritate her.

More power to the user

If the user intentionally closes the balloon, it won’t show up again for all the duration of that session. This feature overrides all your configurations, even if you set the balloon to show up every single time, if the user taps the close button the message won’t be shown until the browser is closed and reopened.

All the Options

The addToHomeConfig object is used to configure the balloon. The options are:

  • autostart: should the balloon be automatically initiated? Default: true.
  • returningVisitor: show the message to returning visitors only. Set this to true and the message won’t be shown the first time an user visits your site. Default: false.
  • animationIn: the animation the balloon appears with. Can be: drop, bubble and fade. Default: drop.
  • animationOut: the animation the balloon exits with. Can be: drop, bubble and fade. Default: fade.
  • startDelay: milliseconds to wait before showing the message. Default: 2000
  • lifespan: milliseconds to wait before hiding the message. Default: 20000
  • bottomOffset: distance in pixels from the bottom (iPhone) or the top (iPad). Default: 14
  • expire: minutes before displaying the message again. 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).
  • message: Define a custom message to display OR set a fixed locale. If you don’t like the default message we have chosen for you, you can add your own. You can also force a language by passing the respective locale (eg: ‘en_us’ will always display the English message). Default: ” (=script decides).
  • touchIcon: if set to true, the script checks for link rel="apple-touch-icon" in the page HEAD and displays the application icon next to the message. Default: false.
  • arrow: shows the little arrow pointing the bottom bar “add” icon. For custom designs you may want to disable it (ie: set it to false). Default: true.

Have a look at the many examples to see how the config works.

Public methods

You can programmatically open the balloon by calling the addToHome.show() function.

You can programmatically close the balloon by calling the addToHome.close() function.

During development you may also need to reset the local and session storages. You can do so by calling the addToHome.reset() function.

Change the balloon appearance

Of course you are free to design the balloon in any way you want. Just change the add2home.css file to your likings.

IMPORTANT: UTF-8 forever!

The script contains the “Add to home” message in many languages. To handle English together with Japanese or Hebrew the script has been encoded in UTF-8 (the standard nowadays).

For this reason it is crucial that the JS file is served as UTF-8. 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 UTF-8 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 you can’t modify the .htaccess file, you may want to remove all languages but English from the script.

Web app capable

To prevent the balloon from appearing once the app has been added to the home screen, remember to add the apple-mobile-web-app-capable meta to your page head:

<meta name="apple-mobile-web-app-capable" content="yes">

If your app is not “web app capable”

If you are not willing to add the web-app-capable tag, you can still prevent the balloon from showing up, but there’s no golden rule here. The easiest way is to check for a special url hash. Have a look at the hash-trick example to get an idea, of course this technique modifies the URL the user is going to bookmark (eg: cubiq.org/#ATHS) and it may interfere with other frameworks that use hash-change event. So use it with caution.

The code is and always be MIT licensed, special thanks to all those who helped translating the script!

/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>