@oneuptime/react-native-replay 14.0.12 → 14.0.13

package/README.md

@@ -193,11 +193,16 @@ const diagnostics = OneUptimeReplay.getDiagnostics();
 
 Diagnostics contain recorder decisions and fixed reason codes, not view text.
 Pass `debug: true` at startup to mirror those codes to the development console.
+`status` is `"paused"` while capture is paused because nobody is using the app,
+and while a session that ended idle waits for the user to come back (see
+[Durability and lifecycle](#durability-and-lifecycle)). The codes
+`idle-paused`, `idle-resumed` and `session-ended-idle` mark those transitions.
 
 Use the current consented session ID to correlate the application's own traces
 and logs with replay. The listener fires immediately when a session exists,
 again on every rotation, and with `null` when capture stops, consent is
-withdrawn, or the session ends idle:
+withdrawn, or the session ends idle (the next session's ID arrives when the
+user is back, or with `captureSession()`):
 
 ```ts
 const unsubscribe = OneUptimeReplay.onSessionChange((sessionId) => {
@@ -221,11 +226,35 @@ server response. AppState backgrounding records visibility, closes the current
 chunk, drains the outbox only when policy and consent permit uploading, and
 pauses sampling; foregrounding resumes with a fresh full snapshot.
 
-Thirty minutes with no touch and no SDK call ends the session at that last
-activity, so time in the background is never added to the end of a session.
-An app left open in the foreground stops sampling then rather than starting a
-session every half hour. The user's next touch, a return to the foreground,
-or `captureSession()` starts a new session on a fresh full snapshot.
+Five minutes without input pauses capture altogether, so an app left on
+screen costs neither battery nor upload. The open chunk closes with an
+`oneuptime.idle-paused` marker and the sampler stops: nothing is sampled,
+checked out, uploaded or recorded until someone is back. Events the app raises
+meanwhile (`track()`, `setRoute()`, JavaScript errors) are dropped, not queued,
+and an error while paused triggers no upload. Input - a touch, the soft
+keyboard showing or hiding, or the app returning to the foreground - resumes
+the same session on a fresh full snapshot followed by an
+`oneuptime.idle-resumed` marker, so the player shows the gap as unrecorded
+rather than as a screen that sat still.
+
+Thirty minutes with no touch and no recorded SDK call ends the session at that
+last activity - for a paused session, at the pause, where its footage ended -
+so time in the background or paused is never added to the end of a session,
+and nothing is sent dated after it. No session starts while nobody is there:
+the user's next touch, keyboard, return to the foreground, or
+`captureSession()` starts a new one on a fresh full snapshot.
+
+Keystrokes on the soft keyboard reach no view the SDK can observe, so the
+keyboard itself stands in for them: its showing and hiding count as input, and
+capture never pauses while it is up, however long someone types. (The
+30-minute session rollover does not depend on it.)
+
+`captureSession()` while paused resumes capture at once, on a fresh snapshot
+with the `oneuptime.idle-resumed` marker and then its own marker behind it; if
+the session has already ended idle, it starts the next session first and the
+marker lands there. Under the error/frustration trigger it also starts the
+upload, opening on that snapshot. It is not input, so if nobody is there the
+next check pauses capture again.
 
 Policy is revalidated without HTTP-cache reuse before every foreground resume,
 after identity changes, and at five-minute intervals while the app remains