docs(mobile-trackers): document isVisible on background-only launches [AISP-1653]

[snowplow-claude-review]

What

Documents the iOS/tvOS tracker fix that makes application_lifecycle.isVisible reflect real app state during background-only launches, and corrects the pages that assert the old behaviour.

• docs/events/ootb-data/mobile-lifecycle-events/index.md — expanded the lifecycle entity section: trackers hold visibility in memory, set it at tracker creation and update it on each foreground/background transition, and background-only launches (silent push, background refresh) are handled differently per platform. Adds a platform table for isVisible during a background-only launch — iOS and tvOS false from the fix version; macOS, watchOS and visionOS true because those platforms have no lifecycle observers; Android true; React Native false; Flutter matching the native tracker — and links to the mobile tracker page for detail.
• docs/sources/mobile-trackers/tracking-events/lifecycle-tracking/index.md — this page carried the same inaccurate claim, so it gets the detailed treatment: new H2s for configuring lifecycle autotracking and understanding the entity value, with H3s on background-only launches and platform coverage. Covers the trigger paths (silent push, background app refresh, background URLSession upload, push-to-start Live Activity), the pre-fix behaviour, and the app-state read at tracker creation. It documents the mapping the tracker actually implements — background is not visible, while both active and inactive are visible — and explains that a normal launch reports inactive at didFinishLaunchingWithOptions, so normal launches are unaffected. A note covers the three knock-on effects: the foreground event is now tracked when a background-launched app is later opened (earlier versions tracked none and the foreground index did not increment), the session controller reports isInBackground as true during the background launch, and session expiry uses the background timeout, which only matters where the two timeouts differ. Platform coverage states that only iOS and tvOS observe lifecycle transitions, and that the Android tracker still reports true for background-only launches.
• docs/sources/mobile-trackers/tracking-events/screen-tracking/index.md — one paragraph in the screen time section on the changed screen_summary attribution: time before the app first becomes visible now counts toward background_sec, where before it counted toward foreground_sec. It also states the remaining limitation honestly — a screen that both starts and ends in the background still counts toward foreground_sec.

A style fix rides along on the lifecycle page: "since v6.0.0" becomes "since version 6.0.0", per the style guide rule against the v-prefix.

Scope

Two of the three pages were outside the original scope. They were changed because they assert the same behaviour the fix changes — the lifecycle page repeated the identical "conditioned by the internal state of the tracker" framing, and the screen tracking page documents the foreground/background attribution the session seed alters — so leaving either would have made the docs self-contradictory. The React Native lifecycle page is untouched (no defect there; it already reads AppState at init), and no previous-versions page was changed.

Version number — confirm before merge

The tracker fix is not released yet, so the docs use 6.3.0 as a placeholder. It appears four times across the three files, and three non-rendering {/* ... */} notes mark all four sites. Grep for iOS tracker version 6.3.0 rather than the bare version string, which also matches unrelated RDB Loader and enrichment lines.

6.3.0 is the next minor after the latest 6.2.5 release. Note that src/componentVersions.js still records 6.2.1 and is stale, and that this is a plain bug fix, which could argue for 6.2.6 instead — so the real number is not determinable until the tracker ships. src/componentVersions.js is deliberately not bumped, as CONTRIBUTING.md ties that to an actual release. Merge this after the tracker release, with the real version substituted at all four sites.

Verification

yarn build passes against the current main with these three files overlaid. The build fails on broken links and anchors, so the new internal links and the background-only-launches and screen-time anchors all resolve, and the generated HTML was inspected to confirm the platform table renders and the MDX comments do not appear in output. Prose was checked by hand against the style guide — Vale is not installed in this environment and is not invoked by any workflow.

A toolchain note for anyone building locally: package.json pins yarn@4.12.0 via packageManager, so corepack enable is required before any yarn command works.

---

Draft PR opened for review — please verify and run CI before merging.

[Snowplow CLA bot (snowplowcla)]

Thanks for your pull request. Is this your first contribution to a Snowplow open source project? Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://docs.snowplowanalytics.com/docs/contributing/contributor-license-agreement/ to learn more and sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	documentation	2b0507b	Commit Preview URL Branch Preview URL	Aug 21 2026, 08:14 AM