@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/android/session-replay.md

@@ -0,0 +1,406 @@
+# Session Replay — Sentry Android SDK
+
+> **Minimum SDK:** `io.sentry:sentry-android:8.33.0`\
+> **Minimum Android API: 26 (Oreo)** — silently disabled on API 21-25\
+> **Status:** Production-ready\
+> **Docs:** https://docs.sentry.io/platforms/android/session-replay/
+
+---
+
+## ⚠️ API Level Requirement
+
+Session Replay requires **Android API 26 (Oreo)** or higher.
+On devices running API 21–25, replay is silently skipped with an `INFO` log — no crash,
+no error, no recording.
+Apps with `minSdk = 21` (covering ~4–5% of devices) have zero replay coverage on those
+devices.
+
+```kotlin
+// Guard in ReplayIntegration.kt (line 128):
+// if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) { return }
+```
+
+---
+
+## How Android Replay Works
+
+Android Session Replay is **screenshot-based**, not DOM-based:
+
+| Dimension         | Web Replay                 | Android Replay                            |
+| ----------------- | -------------------------- | ----------------------------------------- |
+| Recording method  | DOM serialization          | Native view hierarchy screenshots         |
+| Frame rate        | Variable / mutation-driven | ~1 frame per second                       |
+| Privacy mechanism | CSS-based DOM masking      | **Native pixel masking** over screenshots |
+| Touch recording   | Full pointer events        | Tap breadcrumbs only                      |
+| Text in replay    | Selectable, searchable     | Pixel-only — text is in screenshots       |
+
+---
+
+## Installation
+
+`sentry-android` bundles session replay — no separate dependency needed:
+
+```groovy
+dependencies {
+    implementation("io.sentry:sentry-android:8.33.0")
+}
+```
+
+For a lighter build using explicit modules:
+
+```groovy
+dependencies {
+    implementation("io.sentry:sentry-android-core:8.33.0")
+    implementation("io.sentry:sentry-android-replay:8.33.0")
+}
+```
+
+For Jetpack Compose masking support:
+
+```groovy
+dependencies {
+    implementation("io.sentry:sentry-compose-android:8.33.0")
+}
+```
+
+---
+
+## Basic Setup
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    options.dsn = "https://YOUR_KEY@sentry.io/YOUR_PROJECT_ID"
+
+    // Continuous recording — record 10% of all sessions
+    options.sessionReplay.sessionSampleRate = 0.1
+
+    // Error-triggered — buffer 30s and upload when an error occurs
+    options.sessionReplay.onErrorSampleRate = 1.0
+
+    // Production-recommended: both modes together
+    options.sessionReplay.sessionSampleRate = 0.05  // 5% continuous baseline
+    options.sessionReplay.onErrorSampleRate = 0.75  // 75% on error
+}
+```
+
+**Via AndroidManifest.xml:**
+
+```xml
+<meta-data android:name="io.sentry.session-replay.session-sample-rate"  android:value="0.1" />
+<meta-data android:name="io.sentry.session-replay.on-error-sample-rate" android:value="1.0" />
+```
+
+---
+
+## Configuration Reference
+
+Accessed via `options.sessionReplay` (Kotlin) or `options.getSessionReplay()` (Java).
+
+| Option                   | Type                     | Default                                  | Description                                                          |
+| ------------------------ | ------------------------ | ---------------------------------------- | -------------------------------------------------------------------- |
+| `sessionSampleRate`      | `Double?`                | `0.0`                                    | Fraction of all sessions recorded continuously (0.0–1.0)             |
+| `onErrorSampleRate`      | `Double?`                | `0.0`                                    | Fraction captured when an error occurs; buffers 30s prior            |
+| `quality`                | `SentryReplayQuality`    | `MEDIUM`                                 | Video encoding quality preset                                        |
+| `screenshotStrategy`     | `ScreenshotStrategyType` | `PIXEL_COPY`                             | Frame capture method (`PIXEL_COPY` or `CANVAS`)                      |
+| `maskAllText`            | `Boolean`                | `true`                                   | Mask all `TextView` subclasses (includes `Button`, `EditText`, etc.) |
+| `maskAllImages`          | `Boolean`                | `true`                                   | Mask all `ImageView` subclasses                                      |
+| `frameRate`              | `Int`                    | `1`                                      | Frames per second                                                    |
+| `errorReplayDuration`    | `Long` (ms)              | `30_000`                                 | Pre-error ring buffer size (30 seconds)                              |
+| `sessionSegmentDuration` | `Long` (ms)              | `5_000`                                  | How often video segments are uploaded                                |
+| `sessionDuration`        | `Long` (ms)              | `3_600_000`                              | Maximum session length (1 hour)                                      |
+| `networkDetailAllowUrls` | `List<String>`           | `[]`                                     | URL prefixes for network request/response capture                    |
+| `networkDetailDenyUrls`  | `List<String>`           | `[]`                                     | URL prefixes excluded from network capture                           |
+| `networkCaptureBodies`   | `Boolean`                | `true`                                   | Capture HTTP request/response bodies                                 |
+| `networkRequestHeaders`  | `List<String>`           | `[Content-Type, Content-Length, Accept]` | Request headers to capture                                           |
+| `networkResponseHeaders` | `List<String>`           | `[Content-Type, Content-Length, Accept]` | Response headers to capture                                          |
+| `debug`                  | `Boolean`                | `false`                                  | Enable verbose replay diagnostic logging                             |
+| `trackConfiguration`     | `Boolean`                | `true`                                   | Track device orientation and configuration changes                   |
+
+---
+
+## Code Examples
+
+### Video Quality
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    // Choose based on bandwidth/battery vs. fidelity trade-off
+    options.sessionReplay.quality = SentryReplayQuality.LOW    // 80% res, 50 kbps, JPEG q10
+    options.sessionReplay.quality = SentryReplayQuality.MEDIUM  // 100% res, 75 kbps, JPEG q30 (default)
+    options.sessionReplay.quality = SentryReplayQuality.HIGH    // 100% res, 100 kbps, JPEG q50
+}
+```
+
+### Screenshot Strategy
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    // Default — stable, supports all custom masking
+    options.sessionReplay.screenshotStrategy = ScreenshotStrategyType.PIXEL_COPY
+
+    // Experimental — always masks ALL text and images; custom masking rules are ignored
+    options.sessionReplay.screenshotStrategy = ScreenshotStrategyType.CANVAS
+}
+```
+
+> **Canvas strategy warning:** When `CANVAS` is active, `addMaskViewClass()`, XML tags,
+> Kotlin extensions, and Compose modifiers are **completely ignored**. Canvas always
+> masks all text and images.
+> Use only when total masking is acceptable.
+
+### Development Configuration
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    if (BuildConfig.DEBUG) {
+        options.sessionReplay.sessionSampleRate = 1.0  // record all sessions in dev
+        options.sessionReplay.debug = true              // verbose diagnostic logging
+    } else {
+        options.sessionReplay.sessionSampleRate = 0.05
+        options.sessionReplay.onErrorSampleRate = 1.0
+    }
+}
+```
+
+---
+
+## Privacy Masking
+
+### Default Masked Types
+
+These view classes are masked by default:
+
+```
+android.widget.TextView            (+ ALL subclasses: Button, EditText, CheckBox, RadioButton, Switch...)
+android.widget.ImageView
+android.webkit.WebView
+android.widget.VideoView
+androidx.camera.view.PreviewView
+androidx.media3.ui.PlayerView
+com.google.android.exoplayer2.ui.PlayerView
+com.google.android.exoplayer2.ui.StyledPlayerView
+```
+
+> **Masking is hierarchical.** Masking `TextView` also masks every subclass
+> automatically.
+
+### Disabling Default Masking
+
+```kotlin
+// Only if you are certain your UI contains no PII in text or images
+options.sessionReplay.maskAllText   = false
+options.sessionReplay.maskAllImages = false
+```
+
+### Class-Based Masking
+
+```kotlin
+// Mask custom view class and all subclasses
+options.sessionReplay.addMaskViewClass("com.example.ui.CreditCardInputView")
+options.sessionReplay.addMaskViewClass("com.example.ui.SsnField")
+
+// Unmask a subclass whose parent class is masked
+options.sessionReplay.addUnmaskViewClass("com.example.ui.PublicLabelButton")
+```
+
+### Instance-Based Masking via XML
+
+```xml
+<!-- Using the standard tag attribute -->
+<View android:tag="sentry-mask" ... />
+<TextView android:tag="sentry-unmask" android:text="@string/public_product_name" />
+
+<!-- Using the dedicated Sentry privacy tag (preferred — doesn't conflict with other tag uses) -->
+<View ...>
+    <tag android:id="@id/sentry_privacy" android:value="mask" />
+</View>
+
+<TextView android:text="@string/safe_label">
+    <tag android:id="@id/sentry_privacy" android:value="unmask" />
+</TextView>
+```
+
+### Instance-Based Masking via Kotlin Extensions
+
+```kotlin
+// On any View instance
+creditCardInputView.sentryReplayMask()
+productTitleLabel.sentryReplayUnmask()
+```
+
+### Jetpack Compose Masking
+
+> **Requires:** `io.sentry:sentry-compose-android:8.33.0`\
+> **Compose 1.8+ note:** A masking regression for Compose 1.8+ was fixed in SDK 8.32.x —
+> use SDK ≥ 8.33.0 with Compose 1.8.
+
+```kotlin
+// Mask an entire composable subtree
+@Composable
+fun PaymentForm() {
+    Column(modifier = Modifier.sentryReplayMask()) {
+        CreditCardField()   // masked via parent
+        CvvField()          // masked via parent
+        ExpiryDateField()   // masked via parent
+    }
+}
+
+// Unmask safe elements inside an otherwise-masked region
+@Composable
+fun ProductCard(product: Product) {
+    Column(modifier = Modifier.sentryReplayMask()) {
+        Text(
+            text     = product.name,
+            modifier = Modifier.sentryReplayUnmask()  // product name is safe to show
+        )
+        Text(
+            text = userPaymentInfo,
+            // inherits parent mask — sensitive data stays masked
+        )
+    }
+}
+
+// Masking via Sentry tag modifier (alternative)
+Text(
+    text     = "Public info",
+    modifier = Modifier.sentryTag("sentry-unmask")
+)
+```
+
+> **Compose + view flattening:** Compose can optimize away wrapper composables.
+> If masking is unexpectedly dropped, verify the composable is not being flattened by
+> the Compose compiler.
+
+### Masking Priority Order (first match wins)
+
+1. **View-level unmask** — `sentry-unmask` tag / `.sentryReplayUnmask()` / Compose
+   `.sentryReplayUnmask()`
+2. **View-level mask** — `sentry-mask` tag / `.sentryReplayMask()` / Compose
+   `.sentryReplayMask()`
+3. **Class-level unmask** — `addUnmaskViewClass(className)`
+4. **Class-level mask** — `addMaskViewClass(className)` / `maskAllText` /
+   `maskAllImages`
+
+> **ViewGroup inheritance:** A masked parent does NOT automatically mask its children.
+> Each child must be independently masked.
+> An unmasked parent does NOT override class-level masks on children.
+
+---
+
+## Network Capture
+
+Requires `SentryOkHttpInterceptor` or `SentryOkHttpEventListener` from
+`sentry-android-okhttp` (or `sentry-okhttp`):
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    options.sessionReplay.networkDetailAllowUrls = listOf(
+        "https://api.myapp.com/v2"      // capture details for this prefix
+    )
+    options.sessionReplay.networkDetailDenyUrls = listOf(
+        "https://api.myapp.com/v2/auth",    // exclude auth endpoints (tokens)
+        "https://api.myapp.com/v2/payment"  // exclude payment endpoints
+    )
+    options.sessionReplay.networkCaptureBodies      = true
+    options.sessionReplay.networkRequestHeaders  = listOf("X-Request-ID", "Accept-Language")
+    options.sessionReplay.networkResponseHeaders = listOf("X-Response-Time", "X-Cache")
+}
+```
+
+> Retrofit and `HttpURLConnection` apps have no network capture in replay — only OkHttp
+> is supported.
+
+---
+
+## Session Lifecycle
+
+```
+App launches / comes to foreground
+        │
+        ▼
+SDK init → ReplayIntegration.start()
+        │
+        │ [recording at 1 fps, uploading segments every 5s]
+        │
+        ├── app goes background ─────────► pause() + flush current segment
+        │        < 30s background
+        ├── app returns to foreground ───► resume() (SAME replay ID)
+        │        > 30s background
+        ├── app returns to foreground ───► stop() + start() (NEW replay ID)
+        │
+        ├── 60 minutes elapsed ──────────► session ends, new one begins
+        │
+        └── error occurs (onErrorSampleRate mode)
+                   │
+                   └─► last 30s of buffered frames are uploaded
+```
+
+---
+
+## Debug Masking Overlay
+
+During development, enable a colored overlay to visually inspect which regions are
+masked:
+
+```kotlin
+// Get the ReplayIntegration instance
+val replay = Sentry.getCurrentScopes().options.integrations
+    .filterIsInstance<ReplayIntegration>()
+    .firstOrNull()
+
+replay?.enableDebugMaskingOverlay()   // shows colored rectangles over masked regions
+replay?.disableDebugMaskingOverlay()
+```
+
+---
+
+## Best Practices
+
+1. **Always set both sample rates for production** — `sessionSampleRate` for baseline
+   coverage, `onErrorSampleRate = 1.0` for debugging every error
+2. **Start with `MEDIUM` quality** — then adjust down to `LOW` if bandwidth or battery
+   becomes a concern
+3. **Use `maskAllText = true` (default)** — erring on the side of more masking is always
+   safer for user privacy
+4. **Use XML `sentry_privacy` tag over `android:tag`** — the dedicated tag doesn’t
+   conflict with other usages of `android:tag`
+5. **Use Compose `Modifier.sentryReplayMask()` at the layout level** — mask entire
+   sections (payment forms, PII screens) rather than individual fields
+6. **Never enable Canvas strategy in production without testing** — it ignores all
+   custom masking rules
+7. **Set `debug = true` during development** — helps verify masking is applied correctly
+   before releasing
+8. **Test on an API 26 device** — replay silently does nothing on API 21-25; don’t test
+   exclusively on newer devices and assume all users have coverage
+9. **Exclude auth and payment URLs from network capture** — `networkDetailDenyUrls`
+   prevents tokens and card data from appearing in replay
+
+---
+
+## Known Limitations
+
+| Limitation                                    | Details                                                                                                                       |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| API 26+ hard requirement                      | Silent no-op on API 21-25; no fallback or warning unless `debug = true`                                                       |
+| Canvas strategy ignores all masking           | `addMaskViewClass`, XML tags, Kotlin extensions, and Compose modifiers have zero effect with `CANVAS`                         |
+| PixelCopy masking misalignment                | Mask overlay can misalign on views with `setTranslationX/Y`, `setScaleX/Y`, or inside `RecyclerView` with `ItemAnimator`      |
+| 60-minute session cutoff                      | Sessions longer than 1 hour are truncated; a new session starts but replay continuity is broken                               |
+| Compose 1.8 masking regression                | Fixed in 8.32.x — requires SDK ≥ 8.33.0 for reliable masking with Compose 1.8+                                                |
+| OkHttp required for network capture           | `networkDetailAllowUrls` / `networkCaptureBodies` only work with Sentry OkHttp integration installed                          |
+| Trailing frame loss on crash                  | In-memory frames from the current segment are lost if the app is killed mid-segment; completed segments are persisted to disk |
+| No Retrofit/HttpURLConnection network capture | Only OkHttp-based networking is captured in replay                                                                            |
+
+---
+
+## Troubleshooting
+
+| Issue                                          | Solution                                                                                                                            |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| No replays appearing in Sentry                 | Check `sessionSampleRate` or `onErrorSampleRate` > 0; verify device is API 26+ (enable `debug = true` to see skip log on API 21-25) |
+| Masking not applied to custom view             | Add class to `addMaskViewClass("com.example.MyView")` or apply `sentry-mask` tag                                                    |
+| Masking applied but view content still visible | Check masking priority order; a view-level unmask overrides class-level masks                                                       |
+| Compose masking not working                    | Add `sentry-compose-android` dependency; ensure SDK ≥ 8.33.0 for Compose 1.8+ support                                               |
+| Canvas strategy masking all content            | Expected — Canvas strategy masks all text and images regardless of masking configuration                                            |
+| Network requests not captured in replay        | Add `SentryOkHttpInterceptor` and add the API base URL to `networkDetailAllowUrls`                                                  |
+| High battery drain                             | Reduce quality to `LOW`; replay runs at 1 fps but PixelCopy is GPU-accelerated                                                      |
+| Replay ID not linked to log events             | Replay ID is auto-attached to logs and metrics when replay is active; verify both features are enabled                              |