native-update 1.4.9 → 3.1.0

package/docs/social-media-marketing/posts-batch-01.md

@@ -0,0 +1,613 @@
+# Native Update — Posts Batch 01
+
+10 LinkedIn / Facebook posts. Each: 2700–2900 chars (~490–510 words). Hard cap because LinkedIn rejects > 3,000 chars.
+
+Story arc: Problem → Plugin intro → OTA → Store-version check → In-app review → Backend → CLI → Example apps → v3.0.0 architecture → Getting started.
+
+Series tag: **#NativeUpdate10** — used on every post so curious readers can pull the rest.
+
+Mark a post as consumed: replace its heading with `USED — Post NN — …`.
+
+---
+
+## Post 01 — The 7-day fix that almost killed our launch
+
+> "It's a one-line fix. We just need to push it." — Every mobile dev, two minutes before remembering App Store review exists.
+
+If you've shipped a mobile app, you know the feeling. Production is on fire. A typo in a regex is rejecting half the signups. A pricing string says "$9" instead of "$19". The fix is three characters. The deploy path is **seven days**.
+
+For a *web* product you'd ship the fix in 90 seconds and go to bed. For a *mobile* product you write a Slack apology, draft a status-page update, and pray for a fast reviewer.
+
+I've been on the wrong side of that timer enough times that I built the thing I wished existed: **Native Update** — an MIT-licensed Capacitor plugin (and full SaaS ecosystem around it) that lets your app pull a fresh JS/HTML/CSS bundle on next launch. No resubmission required.
+
+### What OTA actually means (and what it does NOT)
+
+OTA replaces the **web layer** of your hybrid app — the bundled JavaScript, HTML, and CSS that renders inside the WebView. It does **not** replace native Kotlin or Swift code, does **not** add new Capacitor plugins to a shipped binary, and does **not** circumvent App Store / Play Store policy on what you're allowed to change.
+
+If your fix is "change the price in a React component" — OTA, 60 seconds.
+If your fix is "add a new Bluetooth Capacitor plugin" — that's still a binary release.
+
+Important boundary. A lot of "live update" pitches blur it. We don't.
+
+### What's in the box
+
+- The plugin: `native-update` on NPM
+- Native Kotlin (Android) + Swift (iOS) — real native code, not a JS shim
+- Laravel 11 + Nova 5 SaaS backend (MIT, self-host)
+- CLI for release management — one command builds, hashes, uploads, rolls out
+- React marketing/dashboard site (Sentry + Clarity + Amplitude wired)
+- 3 example apps as living integration tests
+- 81 passing unit tests + Detox E2E suite
+- MIT license throughout
+
+This is the opener of a 10-part series (`#NativeUpdate10`). Posts 02–10 cover: ecosystem tour, OTA deep-dive, store-version checks, in-app review, the Laravel backend, CLI, example apps, v3.0.0 BREAKING story, getting started.
+
+If you build with Capacitor and you've felt the 7-day-review handcuffs, save this post and follow the series.
+
+### Why this exists
+
+The bet behind Native Update: hybrid mobile apps deserve the same iteration speed as web apps. Capacitor already has the runtime. What was missing was a credible OTA story — plugin + backend + CLI + examples — that wasn't paid-SaaS lock-in. So I built one. MIT, self-hosted, the piece that closes the loop between "I shipped a fix" and "every user has it."
+
+**👉 Try it: `yarn add native-update` or https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #CapacitorPlugin #OTAUpdates #Aoneahsan #TopFree
+
+---
+
+## Post 02 — What's actually in the box (Native Update, end to end)
+
+Most "Capacitor plugin" announcements ship one thing: a TypeScript package on NPM. You install, read a 40-line README, discover the iOS side won't compile, open an issue, wait.
+
+I wanted to ship something different. **Native Update is a monorepo, not just a package.** Eight workspaces, all MIT-licensed:
+
+- `src/` — the Capacitor plugin (TypeScript)
+- `android/` — Kotlin native implementation
+- `ios/` — Swift native implementation
+- `cli/` — release-management CLI
+- `backend/` — Laravel 11 + Nova 5 SaaS backend
+- `website/` — React + Vite marketing/dashboard
+- `example-apps/` — 3 reference integrations
+- `e2e/` — Detox E2E tests on real devices
+
+Post 02 in the **`#NativeUpdate10`** series.
+
+### Why ecosystem instead of "just the plugin"
+
+Every hybrid-update library I integrated before played out the same:
+
+1. Plugin is fine.
+2. Plugin docs assume a backend you don't have.
+3. "Recommended backend" is paid SaaS with no migration path.
+4. Six months in, you've built three quarters of a backend yourself.
+
+So I shipped the backend in the same repo. MIT. Self-host. The plugin and CLI talk to it over HTTP — but the protocol is portable; the Express example app shows how to wrap your own service in it.
+
+### Three independent capabilities
+
+The plugin exposes three things. Use one, two, or all three:
+
+1. **Live / OTA updates** — pull a fresh bundle on next launch
+2. **App-store update checks** — detect users on stale binaries, soft nudge or hard gate
+3. **In-app review prompts** — wrap iOS `SKStoreReviewController` and Google Play In-App Review
+
+Each has its own API surface, its own native implementations in `android/` and `ios/`, and its own unit tests. None depends on the others.
+
+### What's in the box, in detail
+
+- The plugin: `native-update` on NPM, Capacitor SDK
+- Native Kotlin (Android) — real Kotlin, full atomic-swap implementation, hash verification on device
+- Native Swift (iOS) — same parity, same correctness
+- Laravel 11 + Nova 5 backend — bundle hosting, channel + rollout management, Nova admin UI
+- CLI — Node.js binary; one command does build → hash → upload → register → rollout %
+- React + Vite marketing/dashboard site — Sentry + Microsoft Clarity + Amplitude wired with page-view auto-track since 2026-05-06
+- Detox E2E suite — runs the full OTA flow on real devices in CI
+
+### What's NOT in the box (honest disclosure)
+
+- No native code OTA — JS/HTML/CSS only
+- No bypass of App Store / Play Store policy
+- Not a React Native plugin (Capacitor / Ionic / hybrid-WebView only)
+- Not free-tier hostable — the Laravel backend needs a small VPS, ~$5–10/month
+
+**👉 5-minute integration: clone the repo, `cd example-apps/react-capacitor`, `yarn && yarn dev`. https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #Capacitor #OpenSource #Aoneahsan #BestOpenSourceCommunityProject
+
+---
+
+## Post 03 — OTA updates: the 60-second deploy path
+
+> "Production is broken." → 60 seconds later → "Production is fixed."
+
+Post 03 in the **`#NativeUpdate10`** series. Today: how Native Update's OTA path actually works.
+
+### The flow
+
+1. You build your web bundle (`yarn build`)
+2. The CLI hashes it, uploads to your backend, registers a release on a channel (`production` / `staging` / `canary`)
+3. The app on next launch asks the backend: "Newer release on my channel for my binary version?"
+4. If yes: download, verify SHA-256 hash, atomic swap on next start, report back
+5. If the new bundle crashes on boot: **rollback** to the prior known-good bundle automatically
+
+That's the whole loop.
+
+### What you control
+
+- **Channel** — production / staging / canary / whatever you name
+- **Rollout %** — ship to 5% → watch error rate → ramp to 100%
+- **Binary version constraint** — a bundle built for `2.4.x` never lands on `2.3.x`
+- **Mandatory vs. optional** — block app entry until applied, or apply on next natural restart
+
+### What the plugin handles for you
+
+Atomic swap (no half-applied bundles). SHA-256 verification on the device (no MITM swap on hostile coffee-shop Wi-Fi). Rollback on crash-on-boot — automatic, the prior bundle stays on disk. Background download throttling so you're not killing battery / data on cellular. Telemetry: success / fail / which release landed where.
+
+### Where OTA earns its keep
+
+- Hot fixes for production JS crashers
+- Copy / pricing / banner / legal text changes
+- A/B tests that don't need new native capabilities
+- Region-specific variants (channel-pin a subset of users)
+- Fast rollbacks when a release misbehaves — flip the channel back, devices pull prior bundle next launch
+
+### Where OTA does NOT apply
+
+- New native Capacitor plugins
+- Anything in `Info.plist` / `AndroidManifest.xml`
+- New permissions
+- Anything Apple or Google would call "a different app"
+
+I keep saying this on purpose — the OTA pitch gets fluffed in marketing, and integrators end up planning around capabilities the technology doesn't have. The boundary is real. Inside it, OTA is great. Outside it, you're shipping a binary.
+
+### The "but App Store policy?" question
+
+Both Apple and Google allow JS / HTML / CSS bundle updates within hybrid apps. The constraint is: don't use OTA to deliver a fundamentally different app than the one they reviewed. Bug fixes, copy changes, A/B tests, feature flags = all fine and within policy. Pivot from a productivity app to a betting app overnight = they will notice. Be a good citizen and you'll be fine.
+
+**👉 5 minutes against the example app: `yarn add native-update` or https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #OTAUpdates #LiveUpdates #Aoneahsan #TopFree
+
+---
+
+## Post 04 — Your users are on v1.0. The store has v3.2. Now what?
+
+Post 04 in the **`#NativeUpdate10`** series.
+
+Hybrid apps live in two worlds: the web layer (you can OTA) and the native binary (you can't). Sooner or later you ship a native change — a new Capacitor plugin, a permission, a major bump — and the binary on the user's device is a generation behind the binary in the store.
+
+OTA can't fix that. The user has to update the binary. The question is whether you ask them or surprise them.
+
+### The polite-nudge problem
+
+Every mobile team has seen these tickets:
+- "Feature X doesn't work for me." (User on v1.0; feature shipped in v3.0.)
+- "Why does it keep crashing?" (Crash patched in v2.4; user has auto-update off.)
+- "I can't sign in." (Auth library upgraded in v2.7; old binary signs incompatible JWTs.)
+
+You can spend three engineers triaging these, or detect the version drift in the app and tell the user, in the app, that a fresh binary is waiting.
+
+### What the plugin does
+
+Native Update's app-store update check exposes:
+- A check call: "is there a newer binary in the store?"
+- Current store version (so you can show "1.4.0 → 3.2.0")
+- A boolean for "is the gap big enough to enforce an update?" — controlled by your backend, not hardcoded
+- Native deep-link helpers to open App Store / Play Store
+
+You decide the UX. The plugin gives you the signal. Common patterns:
+
+- **Soft nudge.** Dismissible banner: "A newer version is available." User updates when convenient.
+- **Hard gate.** "This version is no longer supported." Used sparingly — for security patches.
+- **Educational toast.** "You're on 1.4.0. Latest is 3.2.0. Tap to see what's new."
+
+### The "what's new" trick
+
+When you nudge a user, *show them why*. The plugin gives you the version string; your backend can give you the changelog. Two-line copy like "We patched the sign-in bug you hit yesterday" converts five times better than "An update is available."
+
+### Three patterns that work in production
+
+1. **Banner on every cold launch.** Dismissible, low-friction. 90% of teams should start here.
+2. **Modal every 7 days.** More aggressive — for apps where version drift causes broken-state experiences.
+3. **Hard gate at a backend-defined floor.** Reserve for security patches and "binary contains an irrecoverable bug."
+
+The plugin gives the signal; UX and backend rules are yours.
+
+### Honest limits
+
+App stores rate-limit version-check endpoints — once per session is plenty. iOS doesn't allow programmatic in-place updates; the button you show must deep-link to App Store. Android allows in-app updates via Play Core; the plugin exposes that path natively.
+
+**👉 Wire the version check on cold launch + soft-nudge banner — cut "you should update" tickets within a week. https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #AppStoreUpdates #MobileDev #Aoneahsan #TopFree
+
+---
+
+## Post 05 — The polite way to ask for a 5-star review
+
+Post 05 in the **`#NativeUpdate10`** series.
+
+iOS (since 10.3) and Android (Google Play In-App Review) both ship a **native review prompt** — a small modal that asks for a rating without yanking the user out to the store. They're rate-limited by the OS, styled to fit the platform, and the platform owners actively prefer them over custom prompts.
+
+Native Update wraps both in a one-line API.
+
+### Why use the native prompt instead of building your own
+
+- **Recommended path.** Apple's HIG says use `SKStoreReviewController`. Google says use Play In-App Review. Doing your own is harder and gains nothing.
+- **Silent on failure.** If the user already rated, or OS rate-limit kicks in, the prompt doesn't show. No spam.
+- **Inline.** Whole review happens without leaving your app. Tap stars, write a sentence, submit, back to your app.
+- **Trusted UI.** Users have seen this exact modal on twenty other apps.
+
+### The capability surface
+
+```ts
+if (await NativeUpdate.canRequestReview()) {
+  await NativeUpdate.requestReview();
+}
+```
+
+Two lines. Cross-platform branching for free.
+
+### When to ask
+
+Don't ask:
+- On first open (no opinion yet)
+- After an error (you'll get one star)
+- During checkout (you'll lose the conversion)
+
+Do ask:
+- After a *successful* completion of the user's primary task
+- After 3+ sessions
+- Never twice in one session (the OS rate-limits anyway)
+
+A canonical pattern: "Did the user just finish their second-or-greater positive flow? Has it been more than a week since the last ask? Yes → request." Two booleans, one if-statement, ship it.
+
+### What this is NOT
+
+- Not a custom review form (the OS owns the form)
+- Not a way to force a 5-star (the user can submit any rating)
+- Not a way to detect what they rated — by design, Apple and Google don't expose this
+
+### What this DOES give you
+
+- The platform-recommended prompt with one line of code
+- Cross-platform branching for free
+- A `canRequest` helper so you can plan UI without tripping OS rate limits
+- Clean fallback if the OS suppresses the prompt (you keep going; nothing breaks)
+
+### Real-world wiring example
+
+E-commerce app: trigger after the user's *second* successful order, not their first. They've experienced the loop twice; one good experience could be luck, two is a pattern.
+
+Content app: trigger after the user has consumed N pieces of content AND opened the app on M+ different days.
+
+Fitness app: trigger after the user's first completed workout streak (e.g., 3 days in a row).
+
+The plugin doesn't care — it gives you `requestReview()`. *When* you call it is product judgment.
+
+**👉 Find your "user just succeeded" moment, drop in `requestReview()` after it. https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #InAppReview #MobileUX #Aoneahsan #SaaSApp
+
+---
+
+## Post 06 — Laravel + Nova: the admin backend the plugin ships with
+
+Post 06 in the **`#NativeUpdate10`** series.
+
+Most Capacitor live-update plugins make you bring your own backend, then sell you a paid one when you give up. I shipped one in the same MIT-licensed repo.
+
+### Why Laravel 11 + Nova 5
+
+- **Why a real framework instead of "a few Express routes?"** Hosting bundles + managing channels + rollouts + version-gating + admin UI is a CRUD problem with auth, validation, queues, and storage. Frameworks are good at CRUD problems.
+- **Why Laravel?** Long-term ecosystem. Robust validation. Eloquent for the data layer. Queue for background work. Storage abstraction that doesn't lock you to one provider. Stable major versions. Predictable deploy.
+- **Why Nova?** Admin UI is half the work. Nova gives you CRUD UI for releases, channels, devices, and analytics in hours, not weeks.
+
+### What the backend exposes
+
+- Releases endpoint (the device asks "newer release on my channel?")
+- Bundle download endpoint (signed, hash-checkable, served via Storage)
+- Telemetry ingest (devices report success / fail of update applications)
+- Admin endpoints (Nova-backed CRUD on releases, channels, rollouts, version constraints)
+- Auth (token-based for the dashboard, signed-URL pattern for bundles)
+
+### What's in Nova admin
+
+Releases (create / list / detail / rollback). Channels. Devices (which release they're on, last-seen, platform). Apps (multi-app config). Analytics dashboards (preferences, /me, rollouts) — added in v3.0.0.
+
+### What's NOT in the backend
+
+No paywall. No cloud lock-in. No "free tier with rate limits that punish you for succeeding." No required third-party services. Storage / queues / cache are all pluggable.
+
+### Self-hosting reality check
+
+Small VPS (1 vCPU, 2 GB RAM) handles thousands of devices for the bundle-distribution workload. Expensive part is bandwidth — bundles are small (200 KB–1 MB), but 100k DAU × 500 KB = ~50 GB egress per release. Use a CDN. Cheap part is everything else — Laravel + Nova are dead boring to operate, which is exactly what you want from infrastructure.
+
+### Why "ships with a backend" matters more than it sounds
+
+Most plugin authors stop at the npm package. They list endpoints in the README and say "implement these." Six months later, the abandoned issue tracker has a dozen "any backend recommendations?" questions. Native Update gives you the reference implementation, in the same repo, MIT-licensed, with the same release cadence as the plugin. Decoupled enough that you can swap it; integrated enough that the protocol can never drift.
+
+**👉 Clone the repo, `cd backend`, `docker compose up`, you're running. https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #Laravel #LaravelNova #Aoneahsan #SaaSApp
+
+---
+
+## Post 07 — The CLI: one command, one rolled-out bundle
+
+> The fewer steps between "code committed" and "users on the new bundle," the more you'll actually ship.
+
+Post 07 in the **`#NativeUpdate10`** series.
+
+Every release path I've seen die slowly died the same way: too many manual steps. "Build, then upload, then SSH, then update a config row, then bump a version, then notify ops." Six steps becomes weekly batches becomes "we don't really do live updates."
+
+The Native Update CLI collapses that into one command.
+
+### Before vs after
+
+**Before:** 6 manual steps, two pages of Confluence runbook, prayer.
+
+**After:**
+
+```bash
+nativeupdate release \
+  --channel production \
+  --rollout 10 \
+  --binary "2.4.x"
+```
+
+Builds the web bundle. Computes SHA-256. Authenticates. Uploads. Registers the release. Sets rollout %. Pins the binary-version constraint. Returns release ID + a one-line "ramp to 100%" command.
+
+### The four CLI muscles
+
+1. **`release`** — the 90% case (above)
+2. **`rollback <release-id>`** — flip a channel back; devices pull prior bundle next launch
+3. **`promote --from staging --to production`** — promote between channels; metadata preserved
+4. **`status`** — show active release on each channel + what's queued
+
+### The auth model
+
+Backend-issued token, scoped to an app + a list of channels. CI uses a token with rights to push to staging/canary; a human uses one with production rights. Two-key reality. Tokens revocable from Nova admin.
+
+### Why this isn't "just a bash script"
+
+Started as one. Got promoted when:
+
+- Hash verification needed proper retries
+- Bundle uploads needed resumable / chunked transfers for slow links
+- Rollout management needed atomicity (two CI jobs landing at once shouldn't race)
+- Operators wanted a `--dry-run` before pulling the trigger
+
+### Where this fits in CI
+
+Build job → produces `dist/`. Test job → must pass. Release-staging → `nativeupdate release --channel staging --rollout 100` on every successful main merge. Release-canary → manual trigger, `--rollout 5`. Release-production → manual, gradual `--rollout 10 → 50 → 100`.
+
+### A typical week with the CLI
+
+Monday: `release --channel staging --rollout 100` after merging the week's PRs.
+Tuesday: QA team flags a regression on staging. `rollback`, fix the bug, `release` again.
+Wednesday: `promote --to production --rollout 5`. Watch Sentry.
+Thursday: `--rollout 50`. Watch some more.
+Friday: `--rollout 100`. Done. Drinks.
+
+That's the rhythm. The CLI is the thing that makes it possible. The fewer keystrokes between your code and your users, the more often you'll actually push.
+
+**👉 Replace your manual upload step today and reclaim half a Friday a month. https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #DevOps #CLI #Aoneahsan #TopFree
+
+---
+
+## Post 08 — Three example apps, because you shouldn't trust a plugin without them
+
+Post 08 in the **`#NativeUpdate10`** series.
+
+My filter for adopting a new mobile plugin: **is there an example app, and does it run?** If yes to both, the plugin is real. If either is no, I'm cautious.
+
+Native Update ships three example apps in the monorepo. Maintained alongside the plugin. Living integration tests.
+
+### example-apps/react-capacitor
+
+The canonical one. Vite + React + Capacitor, integrated end-to-end.
+
+What it demonstrates:
+- Wiring `native-update` into `App.tsx`
+- Configuring channels and binary version in `capacitor.config.ts`
+- `checkForUpdate()` on launch
+- "Downloading…" UI while a bundle pulls in the background
+- Handling the post-update reload
+- Manual "check now" button for testing rollouts
+- `requestReview()` after a contrived "successful action"
+
+If you've never integrated the plugin, this is the example you copy from.
+
+### example-apps/node-express
+
+A small Express service mimicking the Laravel backend's HTTP surface.
+
+Why it exists: some integrators want to validate the plugin against their own backend before adopting Laravel. The Express example documents the exact endpoints they need to implement. It's not the production answer — it's a blueprint.
+
+### example-apps/firebase-backend
+
+The historical Firestore-direct path was removed in v3.0.0 (post 09 is that story). The Firebase example *remains* as a reference for integrators who want the Native Update protocol wrapped around Firebase functions on top of Firestore data they own.
+
+The plugin itself talks Laravel-shaped HTTP. The example shows the protocol can wrap any backend you control.
+
+### Why three and not one
+
+Each app exercises a different backend posture:
+- React-Capacitor → canonical Laravel backend
+- Node-Express → hand-rolled implementation of the protocol
+- Firebase-backend → Firebase-functions wrapper
+
+If the plugin works against all three, the protocol is portable. That's the design constraint.
+
+### What the apps catch
+
+API drift. Compilation breaks on Capacitor major bumps. Bundle-format regressions. iOS / Android divergences when one platform's native code changes. They're not a substitute for the 81 unit tests + Detox E2E suite, but they're a substitute for "I tried the plugin in a real app and the wheels fell off."
+
+A plugin without an example app is a plugin you'll be integrating at 2 AM with zero reference for what "working" actually looks like.
+
+**👉 Clone the monorepo, `cd example-apps/react-capacitor`, `yarn && yarn dev` — working integration in 5 min. https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #Capacitor #OpenSource #Aoneahsan #BestOpenSourceCommunityProject
+
+---
+
+## Post 09 — Why we deleted 3,000 lines of Firestore (the v3.0.0 story)
+
+> "The best architecture decision is the one you can describe in one sentence."
+
+Post 09 in the **`#NativeUpdate10`** series.
+
+Native Update v3.0.0 was a deliberate BREAKING release. ~3,000 lines deleted. The plugin SDK and the website both refactored to talk only to the Laravel HTTP API. v2.x integrators on the Firestore path had to migrate.
+
+We don't take BREAKING releases lightly. Here's the reasoning, with all the trade-offs.
+
+### What v2.x looked like
+
+The plugin supported two backend postures:
+1. **Laravel HTTP** — the canonical backend
+2. **Firestore direct** — the device read release metadata directly via Firebase SDK
+
+On paper this was flexible. In practice it created a shadow API surface: every backend behavior implemented twice, authorization rules modeled in two places, telemetry ingested in two places, tests covering two paths.
+
+### The cost of "two right ways"
+
+- **Surface duplication.** Every release-metadata change required updates in both paths.
+- **Test matrix explosion.** "Does this work on Laravel? On Firestore? When I switch?"
+- **Onboarding friction.** New integrators wasted time deciding which path before integrating.
+- **Documentation rot.** Two paths means two doc trees, one always out of date.
+- **Operational opacity.** Diagnosing a v2.x bug started with "which backend are you on?"
+
+The plugin was carrying ~3,000 lines to support a path that was complicating every other decision.
+
+### Why removal won
+
+- **Laravel was already feature-complete.** Anything Firestore did, Laravel already did, often better.
+- **Single source of truth.** One backend = one authorization model, one telemetry ingest, one set of release-metadata semantics.
+- **Cleaner mental model.** "Native Update talks HTTP to a Laravel backend you control." One sentence. Done.
+- **Test suite shrunk by ~40%.** Every remaining test is more meaningful.
+- **Documentation halved.**
+
+### What integrators on Firestore lost
+
+Honest list:
+- "No extra service to run" — Firestore-direct was attractive because teams already had Firebase
+- A few minor knobs that made sense in Firestore but didn't translate cleanly
+
+### What integrators got
+
+Simpler integration surface. Stable, predictable API. A real admin (Nova UI, not "write Firestore queries"). Server-side-only secrets. Faster plugin releases (every change reasoned about in one model).
+
+### The lesson
+
+If you maintain "two right ways" inside one library and one is consistently winning on every axis (test coverage, doc clarity, ops sanity, integrator velocity), the other isn't a feature — it's a tax.
+
+**👉 v2.x users: read `docs/MIGRATION.md`, schedule the upgrade, all new features land in v3.x. https://nativeupdate.aoneahsan.com**
+
+#NativeUpdate #SoftwareArchitecture #BreakingChanges #Aoneahsan #BestOpenSourceCommunityProject
+
+---
+
+## Post 10 — Five-minute integration: from `yarn add` to your first OTA
+
+Post 10 — final in the **`#NativeUpdate10`** series. The actual five-minute walkthrough.
+
+### Pre-reqs
+
+- A Capacitor app you control
+- A backend URL where Native Update is running (self-host the Laravel from `backend/`, or your own service speaking the protocol)
+- An app token from your backend
+
+### Step 1 — Install
+
+```bash
+yarn add native-update
+npx cap sync
+```
+
+Plugin installed, iOS pod install runs, Android Gradle module linked.
+
+### Step 2 — Configure
+
+In `capacitor.config.ts`:
+
+```ts
+plugins: {
+  NativeUpdate: {
+    backendUrl: 'https://updates.your-domain.com',
+    appKey: process.env.NATIVE_UPDATE_APP_KEY,
+    channel: 'production',
+    autoCheck: true,
+  },
+}
+```
+
+### Step 3 — Wire the API
+
+```ts
+import { NativeUpdate } from 'native-update';
+
+// On launch:
+const r = await NativeUpdate.checkForUpdate();
+if (r.updateAvailable) await NativeUpdate.downloadAndApply();
+
+// Stale binary check:
+const v = await NativeUpdate.getStoreVersion();
+if (v.updateRecommended) showSoftNudgeBanner(v.latestVersion);
+
+// After a successful action:
+if (await NativeUpdate.canRequestReview()) {
+  await NativeUpdate.requestReview();
+}
+```
+
+Three calls, three independent capabilities.
+
+### Step 4 — Build a release
+
+```bash
+yarn build
+nativeupdate release --channel staging --rollout 100 --binary "1.0.x"
+```
+
+CLI builds, hashes, uploads, registers. Returns release ID.
+
+### Step 5 — Verify
+
+Open the app on a test device. Plugin checks backend, sees newer release on `staging`, downloads, applies on next start. Restart. You're on the new bundle.
+
+### Step 6 — Promote to production
+
+```bash
+nativeupdate promote --from staging --to production --rollout 10
+# watch error rate for an hour
+nativeupdate promote --rollout 50
+nativeupdate promote --rollout 100
+```
+
+### Common first-time gotchas
+
+- **Hash mismatch** → re-built but didn't re-upload. Re-run `release`.
+- **iOS doesn't see the update** → missed `npx cap sync`. Re-sync, rebuild in Xcode.
+- **"No update" but there is one** → channel mismatch.
+- **Crash after apply** → rollback kicks in automatically. Check Sentry.
+
+### After integration
+
+- Add a "tap to check for updates" button in Settings for power users
+- Wire `requestReview()` after your strongest "user succeeded" moment
+- Wire store-update-check on cold launch with a soft-nudge banner
+- Add Sentry — when an OTA bundle breaks, you want to see it before users do
+
+**👉 Five steps. Five minutes. Run them today. `yarn add native-update` or https://nativeupdate.aoneahsan.com**
+
+End of `#NativeUpdate10`. If a teammate is stuck on a 7-day review queue, share the package with them. Save them a week.
+
+#NativeUpdate #GettingStarted #CapacitorPlugin #Aoneahsan #TopFree
+
+---
+
+## End of Posts Batch 01
+
+10 posts, each ~2700–2900 chars, ready for LinkedIn / Facebook. Mark `USED — ` once shared.