Prompt users to install our app (PWA/TWA)

### Feature Request

### Problem / Opportunity

Open Library sees significant (and growing) mobile traffic, as global internet access continues to shift toward smartphones. However, the web experience on mobile browsers lacks the persistent visibility and ease-of-return that native-like apps provide. Users who discover Open Library to borrow a book may not return after their session ends, as there's no visual cue (e.g., app icon in the drawer) to remind them of the service. This contributes to low retention despite high initial engagement.
Without an installed Progressive Web App (PWA) or Trusted Web Activity (TWA) wrapper, users must re-type URLs, navigate bookmarks, or rely on search engines to return—friction that reduces repeat visits.

Mobile users are app-oriented: installing an app creates a persistent reminder and seamless re-entry point. An Open Library PWA/TWA would:

Appear in the user's app drawer as a visual nudge ("Oh, let me check if they have that book").
Enable faster load times, offline access (where supported), and push notifications (future potential).
Align with modern web best practices while providing an app-like experience without App Store/Google Play distribution hurdles.

Impact Hypothesis: Prompting installation at high-intent moments will increase PWA/TWA adoption, leading to improved user retention (measured via return visits, borrow frequency, and session depth).

### Success Metrics

Metric | Target | Rationale
-- | -- | --
PWA/TWA Install Rate | >5% of prompted mobile users | Indicates prompt effectiveness without annoyance
7-Day Retention Increase | +10–15% for installers vs. non-installers | Core goal: app icon drives return visits
Prompt Dismissal Rate | <70% permanent dismissals | Users should feel in control

### Proposal

## Proposed Implementation Options (Ranked by UX Quality)

1. **Best: Contextual Prompt on Book Borrow (Recommended)**
- Trigger: After a user successfully borrows a book on mobile.
- Message: _"Get faster access next time—add Open Library to your home screen!"_ [Add to Home Screen] [Not now]
- Rationale: High-intent moment; user has committed to the platform.

2. **Good: Return Visitor Prompt (Cookie-Based)**
- Trigger: User returns to the site (2+ sessions) and hasn’t seen prompt in 30+ days.
- Use `localStorage` or cookie to suppress after dismissal/install.
- Avoids first-visit annoyance.

3. **Acceptable: Post-Login / Account Creation**
- Trigger: After login or new account creation.
- Less ideal than borrow (lower intent signal), but still contextual.

4. **Avoid: Immediate On-Load Prompt**
- Too aggressive; harms first impressions.

---

## Technical Requirements

- **PWA Readiness Audit (Pre-Launch)**
- [ ] Verify `manifest.json` is valid and includes:
- `name`, `short_name`, `icons` (192x192, 512x512), `start_url`, `display: standalone`
- [ ] Confirm service worker registers and caches core assets
- [ ] Test "Add to Home Screen" (A2HS) prompt eligibility:
- HTTPS
- User engagement heuristic (Chrome: ~2 interactions)
- `beforeinstallprompt` event handling
- [ ] Validate TWA (Android) packaging if distributed via Google Play
- [ ] Test on iOS (Safari) and Android (Chrome) — ensure banner appears correctly

- **Prompt UI (Elegant & Native-Feeling)**
```html

```
- Use bottom sheet (mobile-native pattern)
- Respect `deferredPrompt` (don’t force; wait for `beforeinstallprompt`)
- Set `pwa-prompt-dismissed` in `localStorage` with timestamp

---

## Rollout Plan

1. **Phase 1: Audit & Fix**
- Audit PWA/TWA health
- Fix any manifest, SW, or icon issues

2. **Phase 2: A/B Test (Borrow-Triggered Prompt)**
- 50% of mobile borrow-completers see prompt
- Track installs, retention, dismissals

3. **Phase 3: Expand (if successful)**
- Add return-visitor logic
- Explore in-app messaging for logged-in users

---

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| Annoying users | Use intent-based triggers + easy dismiss + long re-prompt cooldown |
| Broken app experience | Mandatory pre-launch audit |
| iOS limitations | Clearly brand as "Add to Home Screen" (not "install app") |

PS: This is mostly generated by AI based on my discussion about what I'd like to do. I've edited it heavily.

### Breakdown

### Related files

Refer to [this map of common Endpoints](https://github.com/internetarchive/openlibrary/wiki/Endpoints):
*

### Requirements Checklist
Checklist of requirements that need to be satisfied in order for this issue to be closed:
* [ ]

### Stakeholders

*

---

### Instructions for Contributors

* **Before** [creating a new branch](https://github.com/internetarchive/openlibrary/wiki/Git-Cheat-Sheet#making-changes-and-creating-a-pull-request) or pushing up changes to a PR, please first [run these commands](https://github.com/internetarchive/openlibrary/wiki/Git-Cheat-Sheet#working-on-your-branch) to ensure your repository is up to date, as the pre-commit bot may add commits to your PRs upstream.