{"id":21633907,"url":"https://github.com/philfung/add-to-homescreen","last_synced_at":"2025-04-12T19:48:28.487Z","repository":{"id":188575068,"uuid":"679005779","full_name":"philfung/add-to-homescreen","owner":"philfung","description":"Easily add website to your IOS/Android/Desktop homescreen.","archived":false,"fork":false,"pushed_at":"2025-04-02T16:53:48.000Z","size":5916,"stargazers_count":194,"open_issues_count":5,"forks_count":52,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-12T19:48:18.556Z","etag":null,"topics":["add-to-homescreen","desktop","desktop-app","desktop-application","desktop-apps","manifest-json","mobile-app","mobile-detect","mobile-detection","mobile-development","mobile-web","mobile-web-app","mobile-website","pwa","pwa-apps","standalone","standalone-app","webapp"],"latest_commit_sha":null,"homepage":"https://philfung.github.io/adhs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/philfung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-15T22:30:21.000Z","updated_at":"2025-04-12T18:14:53.000Z","dependencies_parsed_at":"2024-04-29T05:29:33.547Z","dependency_job_id":"25c83eb2-2fc3-4293-a927-cea7d55ad3e4","html_url":"https://github.com/philfung/add-to-homescreen","commit_stats":{"total_commits":95,"total_committers":5,"mean_commits":19.0,"dds":0.5473684210526315,"last_synced_commit":"f66e157f633114a27100854df3c379ae01a33bb4"},"previous_names":["philfung/add-to-homescreen"],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philfung%2Fadd-to-homescreen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philfung%2Fadd-to-homescreen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philfung%2Fadd-to-homescreen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/philfung%2Fadd-to-homescreen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/philfung","download_url":"https://codeload.github.com/philfung/add-to-homescreen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625500,"owners_count":21135513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["add-to-homescreen","desktop","desktop-app","desktop-application","desktop-apps","manifest-json","mobile-app","mobile-detect","mobile-detection","mobile-development","mobile-web","mobile-web-app","mobile-website","pwa","pwa-apps","standalone","standalone-app","webapp"],"created_at":"2024-11-25T03:14:28.596Z","updated_at":"2025-04-12T19:48:28.466Z","avatar_url":"https://github.com/philfung.png","language":"TypeScript","funding_links":[],"categories":["Tools"],"sub_categories":["Miscellaneous Utilities"],"readme":"# add-to-homescreen 📱💻\nEasily add a website to your IOS/Android/Desktop homescreen ([Demo](https://philfung.github.io/adhs)).\n\n\u003cimg src=\"https://github.com/user-attachments/assets/3e751e86-f438-4a33-b9bb-fc81495fa67c\" width=\"300\"/\u003e\n\n\n\n## Motivation\n\nAdd to home screen allows websites and PWA's to work like native apps without registering in the Apple or Google App Stores. Currently, it is very difficult to get users to add web apps to their home screen, limiting the utility of such websites compared to native apps. See [related Medium blog post](https://medium.com/@philipfung/add-to-homescreen-websites-an-option-for-startups-in-2023-efb92f5e03ad).\n\n## This Library\n\nThis drop-in JS Library for websites effectively guides a user to add the website to their home screen on IOS, Android and Desktop.\n\u003c/br\u003e\u003c/br\u003e\nInstructions and UI in this library have been \"battle-tested\" and have yielded an _~85% home screen install rate_ on IOS and Android across all ages in past implementations.\n\nHere is a [demo (please open on your phone)](https://philfung.github.io/adhs) of library use within a hypothetical app \"Aardvark\" \u003cimg width=\"40\" alt=\"aardvark-icon\" src=\"https://github.com/philfung/add-to-homescreen/assets/1054593/e933af84-9225-4079-8fd7-5af525878693\"\u003e\n\u003c/br\u003e\n\n## Language Support\n\nTranslated to 20+ [languages](https://github.com/philfung/add-to-homescreen/tree/main/src/locales).\n\n## Browser Support\n\nAll major browsers with \u003e 10% market share on IOS/Android/Desktop are supported.\nHere are the guides shown for each platform/browser:\n\n#### IOS - Safari browser\n\n\u003cimg width=\"175\" alt=\"sc-ios-safari\" src=\"https://github.com/user-attachments/assets/a7457b49-b9f7-4748-8571-73672dcfd7f2\"\u003e\n\n#### IOS - Chrome browser\n\n\u003cimg width=\"175\" alt=\"sc-ios-chrome\" src=\"https://github.com/user-attachments/assets/bdfa90eb-f23a-4f81-9d65-3c473d3f181f\"\u003e\n\n#### Android - Chrome browser\n\n\u003cimg width=\"175\" alt=\"sc-android-chrome\" src=\"https://github.com/user-attachments/assets/edbbf840-b33b-4cb9-98da-22db8764cbc2\"\u003e\n\n#### Desktop Windows \u0026 Mac - Chrome \u0026 Edge browsers\n\n\u003cimg width=\"475\" alt=\"sc-desktop-chromeedge\" src=\"https://github.com/user-attachments/assets/86727d6f-ade9-4e7a-b1bf-b0e2b2dcd1ed\"\u003e\n\n#### Desktop Mac - Safari browser\n\n\u003cimg width=\"475\" alt=\"sc-desktop-safari\" src=\"https://github.com/user-attachments/assets/384b7ed8-7acf-4bee-805c-36ca820c19ee\"\u003e\n\n#### In-App Mobile Browsers\n\nIn-App browsers on popular social apps are supported.  Users are guided to open the link in the system browser, then the standard add-to-homescreen flow appears.\n\n  * Instagram ([IOS](https://github.com/user-attachments/assets/0d3ab224-1ac7-454e-b75d-21f6c52ffa87), [Android](https://github.com/user-attachments/assets/7e1d11fd-31ba-4b27-a13d-6beb079b4204))\n  * Facebook ([IOS](https://github.com/user-attachments/assets/4c8121a2-3c62-402f-be05-0c54bf108ddc), [Android](https://github.com/user-attachments/assets/45701ac3-d337-4fc4-8e82-3d03236bf3a5))\n  * X / Twitter ([IOS](https://github.com/user-attachments/assets/ed01b58e-5aab-48b9-8c42-d21d24cd2c03), Android - opens in system browser)\n\n## Installation\n\n### Prerequisite\n\nMake sure your site has the minimum requirements for installing a web app on homescreen for IOS and Android and Desktop.\n\n1. At `https://your-website.com/apple-touch-icon.png`, include a square icon of your app that is (1) at least 40 x 40 pixels and (2) specifically named `apple-touch-icon.png`([example](https://github.com/philfung/add-to-homescreen/blob/main/apple-touch-icon.png)).\n2. At `https://your-website.com/manifest.json`, include a web manifest file `manifest.json` ([example](https://github.com/philfung/add-to-homescreen/blob/main/manifest.json)). Reference the manifest in your index HTML file.\n\n   `index.html`\n\n   ```html\n   \u003chead\u003e\n     ...\n     \u003clink rel=\"manifest\" crossorigin=\"use-credentials\" href=\"manifest.json\" /\u003e\n     ..\n   \u003c/head\u003e\n   ```\n\n### Usage (If you're not making changes to library)\n\nThis should be a quick drop-in library into your website.\n\n1. Include the library JavaScript and CSS files in your header (You can use [JSDelivr CDN](https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@master/dist/) if you're just using the library directly and not making any changes):\n\n   `index.html`\n\n   ```html\n   \u003chead\u003e\n     ...\n     \u003clink\n       rel=\"stylesheet\"\n       href=\"https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@3.2/dist/add-to-homescreen.min.css\"\n     /\u003e\n     \u003cscript src=\"https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@3.2/dist/add-to-homescreen.min.js\"\u003e\u003c/script\u003e\n     ...\n   \u003c/head\u003e\n   ```\n\n   The code above will include a JavaScript file containing all the available translations for the locales this library supports. It is highly optimized to be small and quick to deliver over mobile networks. If however you want to\n   be even more highly optimized, the library also has JavaScript files built with just a single locale of translations, which is about 60% smaller.\n\n   For example, the Spanish file `add-to-homescreen_es.min.js` can be included as below. If you have a dynamic server environment and know the user's preferred locale, this can be a good option. To see all the supported locales, look in the `dist` folder.\n\n   ```html\n   \u003chead\u003e\n     ...\n     \u003clink\n       rel=\"stylesheet\"\n       href=\"https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@3.2/dist/add-to-homescreen.min.css\"\n     /\u003e\n     \u003cscript src=\"https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@3.2/dist/add-to-homescreen_es.min.js\"\u003e\u003c/script\u003e\n     ...\n   \u003c/head\u003e\n   ```\n\n2. Call the library onload.\n\n   `index.html`\n\n   ```javascript\n   \u003cscript\u003e\n   document.addEventListener('DOMContentLoaded', function () {\n    window.AddToHomeScreenInstance = window.AddToHomeScreen({\n     appName: 'Aardvark',                                   // Name of the app.\n                                                            // Required.\n     appNameDisplay: 'standalone',                          // If set to 'standalone' (the default), the app name will be diplayed\n                                                            // on it's own, beneath the \"Install App\" header. If set to 'inline', the\n                                                            // app name will be displayed on a single line like \"Install MyApp\"\n                                                            // Optional. Default 'standalone'\n     appIconUrl: 'apple-touch-icon.png',                    // App icon link (square, at least 40 x 40 pixels).\n                                                            // Required.\n     assetUrl: 'https://cdn.jsdelivr.net/gh/philfung/add-to-homescreen@3.2/dist/assets/img/',  // Link to directory of library image assets.\n\n     maxModalDisplayCount: -1,                              // If set, the modal will only show this many times.\n                                                            // [Optional] Default: -1 (no limit).  (Debugging: Use this.clearModalDisplayCount() to reset the count)\n     displayOptions:{ showMobile: true, showDesktop: true }, // show on mobile/desktop [Optional] Default: show everywhere\n     allowClose: true, // allow the user to close the modal by tapping outside of it [Optional. Default: true]\n     showArrow: true, // show the bouncing arrow on the modal [Optional. Default: true] (highly recommend leaving at true as drastically affects install rates)\n   });\n\n    ret = window.AddToHomeScreenInstance.show('en');        // show \"add-to-homescreen\" instructions to user, or do nothing if already added to homescreen\n                                                            // [optional] language.  If left blank, then language is auto-decided from (1) URL param locale='..' (e.g. /?locale=es) (2) Browser language settings\n   });\n   \u003c/script\u003e\n   \u003c/body\u003e\n   ```\n\nHere's an [example implementation](https://github.com/philfung/add-to-homescreen/blob/main/index.html).\n\n#### Special Case: calling the UI later\n\n2-alternate. if you're calling the UI NOT onload, but sometime after (for example, in an onclick() handler for an \"Install App\" button), then\nyou should still create your the instance onload, but call your UI later on the instance variable with .show()):\n\n`index.html`\n\n```javascript\n\u003cscript\u003e\ndocument.addEventListener('DOMContentLoaded', function () {\n\n   window.AddToHomeScreenInstance = window.AddToHomeScreen({...\n}));\n\ndocument.getElementById('my_install_app_button').addEventListener('click', function () {\n   window.AddToHomeScreenInstance.show('en');\n});\n\u003c/script\u003e\n\u003c/body\u003e\n```\n\nThis is because some handlers must be created onload.\n\n### Usage (If you're making changes to library)\n\nAddToHomescreen builds multiple copies of the library, all to the `dist` folder, each with their own intended usage.\n\nThe most likely JavaScript file that you'll use is `add-to-homescreen.min.js`. This is the minified production read code.\n\nIf you are debugging a change you made to the library, the `add-to-homescreen.js` file is an unminified version of the code, which you can use by loading the `/debug` path in the server below.\n\nThe library also builds multiple other copies of the JavaScript code that are specific to an individual locale, for\nexample `add-to-homescreen_es.min.js` only contains the Spanish translations. These are intended to be used by\napplications that are highly concerned with the amount of JavaScript code that is downloaded on a mobile device, and they\nare generally less than half the size of the default file. If your server is aware of the desired locale and you have the\nability to change what file is loaded at page load time, these files can be a good choice.\n\n1. Make changes\n2. Build the library into the `dist` directory\n\n   ```\n   npm install\n   npm run build\n   ```\n\n   This will build all variations of the JavaScript file and start a server for your testing. 3. Test locally:\n\n3. Start local server\n\n   ```\n   npm run build\n   npm run start\n   ```\n\n   Load an example page http://127.0.0.1:8081, or load an example page with unminified code at http://127.0.0.1:8081/debug\n\n4. Save the [dist](https://github.com/philfung/add-to-homescreen/tree/main/dist) directory to a CDN of your choice.\n   Follow the steps in the previous section.\n\n## Dependencies\n\nNo dependencies. This is written in raw ES6 javascript and all css is namespaced to minimize codebase conflict and bloat.\n\n## Contributors\n\n- Thanks to [Shane O'Sullivan](https://github.com/shaneosullivan) for a a massive refactor to improve performance and i18n.\n\n## License\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilfung%2Fadd-to-homescreen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphilfung%2Fadd-to-homescreen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphilfung%2Fadd-to-homescreen/lists"}