Diamond Stone: getting the app onto a phone
Date: 2026-11-11. Revision 1. Screens in docs/ui-shell-mockup.html, section
"Installing the app"; flows in docs/system-flows.html and docs/user-flows.html.
How staff, customers and drivers get the app, where and when they are asked, what happens after, how it updates, and what goes wrong. Based on browser documentation, the notes of people who have shipped installed web apps, and the little formal research that exists, all read on 11 November 2026. Points marked (unverified) were not read at a primary source. Nothing has been tried on the S25 or A55 yet.
1. What the research changed
| Earlier plan | Finding | Now |
|---|---|---|
| Installing works in Chrome and Samsung Internet | Samsung Internet installs are blocked on Android 14 and later by Play Protect ("built for an older version of Android"). An open fault with no fix; several products now send Samsung Internet users to Chrome | Staff install from Chrome only. A person who opens the install page in Samsung Internet is sent to Chrome. Customers in Samsung Internet are not offered install there |
| Customers arrive from WhatsApp links and can be offered install | On an iPhone a link never opens an installed web app; it opens Safari, which has separate storage and a separate sign-in. Only a notification opens the installed app | On iPhones the portal is a browser experience first. Install is offered only for alerts, and every link works in Safari |
| One install, then signed in | On an iPhone the installed app does not share Safari's storage, so the person signs in again inside it | Staff sign in after installing, never before. Customers are told they will confirm their number once more |
| An Install button for everyone | iPhones give no button and no way to detect a finished install. On Android the button exists only when the browser offers it | A button on Android when offered; pictured steps otherwise; the server records an install only when the app is opened from the home screen |
| Passkey made at first sign-in | A passkey's reach depends on the domain it is tied to. Browsers inside apps (WhatsApp, Instagram) often cannot use passkeys at all | The passkey is tied to the main domain, so one passkey serves all three apps. Inside another app's browser, sign-in is by code only |
| Three apps, layout undecided | Several apps on one address share storage and permissions and break install prompts | Three addresses, one app each (already the direction; now a rule) |
| The app updates itself | On Android a changed name or icon reaches installed phones only after a day or more, on Wi-Fi and charging; on iPhones never without re-installing. A carelessly updated app can leave old screens talking to new code | Name and icon are chosen once. Code updates are offered at a safe moment; the server refuses phones on a version too old |
2. Who installs what
| Person | Installs? | Where they are asked | Why |
|---|---|---|---|
| Staff | Yes, required. From Chrome, before first sign-in | The invite link or a code scanned in person | Alerts, fingerprint, working without signal, and one known setup to support |
| Customer, Android | Optional | In the portal, after something useful (a quote accepted, a delivery to follow). Once | One tap to their orders; alerts; links from messages open the app |
| Customer, iPhone | Optional, and only worth it for alerts | Under "Alerts" in the portal, with pictured steps | Links from messages will still open Safari, so the gain is alerts alone. Said plainly |
| Customer who visits twice a year | No | Never asked | The portal works fully in a browser tab |
| Website visitor | No | Never asked | Nothing to install; the site is pages |
| Outside driver | No, never | Not asked | One job, one link, any browser, no fingerprint |
| Own driver (later) | The small Android app, by the administrator | In person | Location while a job is open (docs/MODULES.md) |
| Logistics company, auditor | Optional, as a customer | As a customer |
3. Staff: the process
Done once per person, ideally in person on their first day. Five minutes.
- The administrator adds the person (name, phone, role). The system makes a one-time invite that ends after 7 days and works on one phone.
- The person gets the link by WhatsApp, or scans a code shown on the administrator's phone. Scanning is preferred: the phone's camera opens Chrome directly.
- Wrong browser? If the link opened inside WhatsApp or in Samsung Internet, a page says so and offers one button, "Open in Chrome", with "copy the link" beneath.
- The install page has the person's name, three reasons in pictures, and one button. If the phone offers no button, the same three steps are shown by hand with pictures of the real menu.
- The person opens the app from the home screen. The app checks that it is running installed; if not, it says "open it from your home screen".
- Sign-in happens here, inside the installed app: the code, then the fingerprint. The passkey is made in the place it will be used.
- Two questions, each with its reason: keep the app's data safe on this phone; turn on alerts. Each on a tap, never on load.
- The administrator's Phones list shows the person as ready: phone, browser, version, alerts.
What the administrator checks on the phone: the icon has no small browser badge on its corner (a badge means it was added as a shortcut, which gets no updates and can be added twice); and that there is only one Diamond Stone icon.
If it goes wrong: "Ask for help" on the install page sends the phone's model, browser and version to the administrator, so nobody has to describe their phone.
Company phones without Google services (some Huawei and Honor models) can only add a shortcut, not a full install. The staff phones chosen (S25, A55) are not affected. A person who brings such a phone can use the app in the browser; it is noted on the Phones list.
Not chosen, and why
| Way | Why not now |
|---|---|
| Pushing the app to phones from Google's admin console | Needs a higher Workspace edition and managed devices. Worth revisiting only if phones become company-managed |
| Wrapping the app for the Play Store | Adds a store account, review and a second thing to update, for fifteen people who can scan a code. The driver app (later) is the one case for it |
| Letting staff use whichever browser | Two installs from two browsers hold separate data. One browser means one thing to support |
4. Customers: when and how they are asked
Rules, from the published guidance and from what teams report:
- Never on arrival, never during a form, never before sign-in.
- After a moment that shows the value: a quote accepted, a delivery to follow, a second visit in a week.
- Once. "Not now" is remembered and the offer does not return unless something changes (a new order begins). It is always under Me → This phone.
- It is a card in the page, not a pop-up, and it says what they get: "Follow this delivery from your home screen and be told when it leaves."
- Hidden when already installed, in a browser that cannot install, and inside another app's browser.
There is little hard evidence on timing. One informal study found that 4 in 10 people already knew "Add to Home Screen"; no rigorous study with numbers was found. So this is measured once live (section 9), not assumed.
| Customer's phone | What they see |
|---|---|
| Android, Chrome | A card with an Add button. One tap, then the phone's own confirmation |
| Android, Samsung Internet | No offer here. Under Me: "To add Diamond Stone to your home screen, open this page in Chrome" |
| Android without Google services | "Add a shortcut" with steps. It works, without alerts on some phones |
| iPhone, Safari | Under Alerts: three pictured steps (Share, Add to Home Screen, Add), and the note that they will confirm their number once more inside the app |
| iPhone, another browser or inside WhatsApp | "Open in Safari" first, with how |
| Any phone, inside another app's browser | Everything works with the one-time code. No install offer and no fingerprint there |
5. Links, and which thing opens
| Link tapped | Android, installed from Chrome | iPhone, installed |
|---|---|---|
| In WhatsApp, to an order | Opens the installed app | Opens Safari. The person may need to sign in there too |
| In an email | Opens the installed app | Opens Safari |
| A notification | Opens the installed app | Opens the installed app |
So: every link must work for someone who is signed out, and take them to the same record after sign-in, in whichever place it opens. Messages to iPhone customers who have installed lead with the notification, which is the only thing that opens their app.
WhatsApp opens ordinary chat links in the phone's browser today. Links in business template messages can open inside WhatsApp's own browser, and a wider in-app browser on iPhones was reported in testing in October 2026 (unverified). The "open in your browser" page is there for that.
6. What is built
| Matter | Decision |
|---|---|
| Addresses | Three: staff, portal, website. One app each. Never one inside another |
| Identity | Each app has a fixed identity that never changes, so its address can |
| Names | Distinct on the home screen: "Diamond Stone" (portal) and "DS Staff" (staff), with different icon backgrounds, so nobody opens the wrong one. Names in Latin letters work in both languages; iPhones ignore translated names |
| Icons | 192 and 512, a 512 "maskable" one with the mark inside the safe circle, a 180 for iPhones. From docs/brand/ |
| Install sheet | Screenshots and a one-line description, so Chrome shows its fuller sheet |
| Colours | Bar and splash colours from the brand, with a dark variant |
| Shortcuts on the icon (Android: press and hold) | Staff: Scan, Search, Add. Portal: My orders, Papers |
| Count on the icon | Android installs from Chrome, and installed iPhones: the Halo's "needs you" count |
| Offline | The app shell and a plain "no signal" page, so the icon always opens something |
| Passkey | Tied to the main domain, so one fingerprint enrolment works across the three addresses and in the installed app. Tested on both phones and an iPhone |
| Other apps' browsers | Detected by name (WhatsApp, Instagram, Facebook, Google's app). Code sign-in only; "Open in Chrome" on Android through a link that falls back to a plain page; pictured steps on iPhones |
| Storage | Asked to be kept (browsers may otherwise clear it). The phone never holds the only copy of anything; the server is the record |
| iPhone specifics | Start-up images, safe areas, a Back control inside the app (there is no system one), and a test of the camera in the installed app, where faults are reported |
| Knowing it is installed | The app sees how it was opened and tells the server on each start. Nothing can tell a browser tab that an installed copy exists on an iPhone |
7. Updating
- Code and screens: a new version is fetched quietly. The Omnibar offers "New version ready · Restart" when the person is idle, never mid-form. After 7 days it applies at the next opening.
- Too old to be safe: the server knows each phone's version. Below a set minimum, actions that post are refused with "Restart to update".
- Checked on every return to the app, not only at start, because phones keep apps open for days.
- Name and icon: treated as permanent. On Android a change arrives after a day or more, only on Wi-Fi and charging, and never for an app that is not opened. On iPhones only by removing and adding again.
- The file that describes the app is never renamed or moved; doing so stops Android checking for a month.
- The Phones list shows each person's version; an old one is a row to chase.
8. Leaving, losing, replacing
| Event | What happens |
|---|---|
| The person signs out | Local data is cleared; the icon stays and opens the sign-in screen |
| A phone is lost | The administrator ends that phone's sessions and removes its passkey from the Phones list. Nothing readable is left, as local data is locked by the fingerprint |
| A new phone | A new invite; install; sign in. Unsent work on the old phone is lost only if it never had signal, and the list shows what was unsent |
| The person leaves the company | Sessions end at once. Removing the icon is not needed for safety |
| The app is removed | On iPhones its data goes with it. On Android some may remain in Chrome; signing out first clears it. The removal steps are in Help |
9. What to measure
Per app and per kind of phone: offers shown, accepted, dismissed; installs completed (opened from the home screen); how long staff setup takes; alerts accepted; phones on an old version; people who arrive inside another app's browser and whether they get out. If customers rarely accept, the offer is reduced, not repeated.
10. To try on the phones before building further
On the S25 and A55 in Chrome and Samsung Internet, one iPhone on each of iOS 17, 18 and 26, and one Android phone without Google services:
- Install from Chrome by button and by menu; confirm a full install (no browser badge).
- Confirm the Samsung Internet fault still exists; confirm the hand-off to Chrome works.
- Open a WhatsApp link to each app, free-typed and from a template, on each phone.
- The fingerprint across the three addresses, and inside the installed app on an iPhone.
- Sign-in again after installing on an iPhone; whether the first sign-in carries over.
- Alerts: the question, a refusal, and turning them on later.
- An update while a form is half filled.
- Arabic: the name under the icon, the install sheet, the steps.
- The Halo band under the status bar when installed (already on the list).
11. Problems people will meet
| Problem | Answer |
|---|---|
| "I tapped the link and nothing can be installed" (inside WhatsApp, or Samsung Internet) | Detected; one button to Chrome |
| Two Diamond Stone icons | One browser for staff; distinct names for the two apps; the administrator checks at setup |
| An icon with a small browser badge | It is a shortcut. Remove it and install from Chrome |
| "It asked me to sign in again" (iPhone) | Said in advance on the steps screen; the code is one tap from the message |
| Installed, but links still open the browser (iPhone) | Explained under Alerts; notifications lead |
| Alerts refused by mistake | Me → This phone shows how to turn them on in the phone's settings, with pictures |
| The app shows old screens | Checked on every return; Restart offered; the server refuses versions too old |
| No Back button (iPhone, installed) | The app's own Back in the top bar on every screen below Home |
| The phone cleared the app's data | Nothing lived only on the phone; sign in again and it is all there |
| "Which one do I install?" | Staff get a staff link; customers are never shown the staff app |
| An older phone or browser | Below the supported versions the app runs in the browser without install, and says so |
| A person will not install | Staff: it is required, and the administrator helps in person. Customers: never pressed |
12. Decisions
- Staff install is required, from Chrome, before sign-in. Proposed: yes.
- Home-screen names: "DS Staff" and "Diamond Stone". To choose.
- Customers on iPhones are offered install only for alerts. Proposed: yes.
- A forced update after 7 days, and a minimum version below which posting is refused. Proposed: yes.
- No Play Store wrapper and no managed install for now. Proposed: yes; revisit with the driver app.
13. Sources
Read directly: web.dev on install criteria, WebAPKs, manifest updates, promoting install, detection, updates, and several apps on one domain; Chrome's notes on the richer install sheet, manifest localisation and Android intents; MDN on installing; WebKit's notes on Safari 26, storage policy and web push; Maximiliano Firtman's notes on iPhone and Chrome web apps (October 2026); the Samsung Internet fault report and Progressier's notice about it; Corbado and passkeys.dev on passkeys inside other apps' browsers; Google's help on private Android web apps; Mozilla's 2023 note on "Add to Home Screen"; Statcounter for Oman (October 2026: Apple 19 %, Samsung 19 %, Xiaomi 15 %, then Vivo, Oppo, Honor). From summaries only (unverified): WhatsApp's in-app browser on iPhones; notification acceptance rates; case-study figures; passkey faults in installed iPhone apps. No rigorous study of install-prompt timing was found.