Add to Homescreen: the WordPress plugin

Developing WordPress plugins is all you hate about PHP! All my respect to WP plugin developers because coding clean, functional, secure add-ons for that platform is a real pain! Anyway, if you want the latest Add to Homescreen updates on your WordPress site, the official plugin is finally landed!

There are already a couple of Add to Homescreen plugins for WordPress (some free, some commercial), but this is the real deal: the only Official Add to Homescreen WordPress plugin around and it’s open source and free.

I thought it was easy to write a wrapper for my little script but it turned out all but a simple task. Making WordPress plugins is easy, making good WordPress plugins is a whole different story. Documentation is lacking and fragmented. Best practices are spread all over the web and they change frequently. You never know which is the best hook to use for the task and you never know when the hook will be actually executed.

So, my respect to the many WP developers out there because it’s a hell of a job.

What is it all about again?

This is the Official WordPress plugin for the Add To Homescreen javascript. The WordPress plugin guides you through the rather complicated javascript widget configuration.

This is the only WordPress plugin developed by the same author of the javascript (yes, me!). If you wish to be always up to date and receive the latest bug fixes, this plugin is probably your best bet.

The plugin opens an always-on-top message inviting your mobile users 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. Windows Phone support is planned for a future release.

Plugin Features

The main reason I developed an official WP plugin is to reach a wider audience and get better bug reports. This is the best way for me to have a direct contact with the script user base and for you to get the latest updates and bug fixes.

The currently available plugins are all very good but I feel they fail in ease of use. The original Add to Homescreen script can be easily integrated into WP without any plugin, just add a couple of lines in the page head and you are done.

If you need a plugin I guess you are expecting more. ATH configuration is rather complicated due to the hackish nature of the script. My WP plugin tries to make things simple, the basic configuration has just 4 options, and that’s all you need if you don’t really want to dig deeper into the plugin.

Another important feature is the User tracking. You can easily track how many times the call out has been displayed and how many times your application has been added to the home screen.


Bear in mind that we do not have a native event we could hook to to know if the web app has been effectively added to the home screen. ATH makes an educated guess which I believe is about 80% accurate (unless you have a web-app-capable website, in which case we are pretty close to 100% accuracy).

The plugin is in early stage of development, so more features are luckily going to be added (given users’ interest). At the top of my to-do there’s Google Analytic integration, it’s fairly easy to add and gives you a central point of access to all your site statistics.

Quick Walk-through

The easiest way to install the plugin is from the plugin section of the admin console. Click Add new and search “Homescreen”. The plugin full name is “Official Add to Homescreen” by Matteo Spinelli. Click on Install Now and from now on you’ll always get the latest updates.

Alternatively you can download it from the WordPress plugin page and manually upload it to your site wp-content/plugin directory.

Once installed head to Settings > Add to Homescreen and you’ll be greeted with the following screen.

Basic Configuration

The first thing to do is to upload your application icon, or the icon that will be installed on the user’s homescreen.

Click on Add/Change Image and select the image you want to use from the media manager. For optimal results try to use a square image of at least 196×196 pixels.

The Basic options screen offers 4 presets that automatically configure the plugin behavior. You shouldn’t need to explore the Advanced options, but if you feel adventurous you can select a preset first and later fine tune the plugin from the Advanced screen.

The available presets are:

  • Anonymous: This is the safest option. It doesn’t interfere with other plugins and you never risk to show the call-out to users who already added the website to the homescreen. The catch is: the stats are disabled and the message is shown only one time per user.
  • Display Once: If your website doesn’t already take advantage of #hash navigation you can safely select this option. The message is still displayed only once per user, but the statistics are enabled and you can track how many times your site has been added to the homescreen.
  • Always Show: The message is shown once a day until the user adds the website to the homescreen. Users are tracked.
  • Silent: If you wish to track your users but not to show the call-out, this is your option.

By default the ATH mechanism to detect if the website has been added is with a token in the URL. This token can be a hash (, a query string ( or a clean url ( By default the plugin uses a hash, but you can select your preferred mechanism from the Advanced options.

I highly recommend to also read the full documentation for the javascript component to better understand how the plugin works under the hood.

Future Development

I plan to add better statistics, multi-site support, translations in various languages and definitely better documentation… but this is a free, open-source software. If you like it and you wish to support future development, please consider sponsoring the WordPress plugin and the javascript widget!

3 thoughts on “Add to Homescreen: the WordPress plugin”

  1. Hi

    How do I find the data in my Google analytics?

    I’ve enabled use analytics but not sure where to find the data!


  2. If I deleted the icon that was added to my phone, what settings should I choose to prompt the user to add it again.

  3. Hello im very interested in your plugin i watch this in the site but is no longer available to buy, i would like to buy please, but i also would like to ask you if theres any chance to modify it by yours, to take the action of redirect to another site when app icon is saved, what i have in mind is this, make homepage for instructions to install trought this method, and when they save it, this icon app that saves on the home screen, could redirect them to the original site, this for take care of my privacy url of the site. Could this be possible? And how much please? Sorry my bad english im from mexico not speaking good your language

Comments are closed.