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.
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.
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
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).
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!
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:
<title>Add To Home</title> ... <script src="../../src/addtohomescreen.js"></script> <script> addToHomescreen(); </script>
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.
ATH accepts one option parameter to customize the script behavior.
To change the start up delay for example you could use the startDelayoption.
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-capableapplications that need full screen viewing to be accessed (eg: games). - skipFirstVisit: setting this to
trueprevents 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.
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.standaloneproperty 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
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
maxDisplayCountto 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.
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.
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.
Of course you can bypass the automatic triggering and open the call out programmatically. To do so you have to set the autostart: falseoption.
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.
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.
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.
Posted](https://s3-eu-west-1.amazonaws.com/froala-eu/temp_files%2F1549905050002-1549905050002.jpeg)Author[matteo](https://web.archive.org/web/20180207041409/http://cubiq.org/author/matteo)Posted){kind=link}
https://highlifeng.com/hausa[Hausa songs ](https://highlifeng.com/hausa)