docs(session-replay): add 'What defines a single replay?' FAQ

docs/session-replay.mdx

@@ -3,13 +3,13 @@
 title: "Session Replay: Watch playbacks of user digital experiences"
 ---
 
 Mixpanel Session Replay provides the fastest way to gain a comprehensive understanding of your customers and make informed product decisions by combining both quantitative and qualitative insights.
 
 While analyzing customer journeys using Mixpanel's analytics, you can identify **where** customers drop off. Now, with Mixpanel Session Replay, you can quickly follow up by exploring **why** customers drop off.
 
 ## Plan Availability
 
 Session Replay is available for customers on Free, Growth, and Enterprise plans. Customers must be on the latest Mixpanel plans to access free replays. Free replays reset monthly, and do not rollover to subsequent months.
 
 | Plan | Replay Allowance | How to Access |
 |------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
@@ -19,7 +19,7 @@
 
 ## Implementation
 
 Session Replay is supported on four primary platforms: Web, iOS, Android, and React Native. You can use Session Replay with CDPs (e.g., Segment and mParticle) on both Web and Mobile. We also support Electron desktop apps.
 
 See our developer guides on implementing Session Replay for these platforms below:
 
@@ -36,7 +36,7 @@
   UI Controls is currently available for Web, iOS, and Android. Support for React Native and Flutter is coming soon.
 </Note>
 
 With UI Controls, teams can manage Session Replay sampling directly from the Mixpanel UI — no code changes or redeployment required. This is available exclusively to customers with the paid Session Replay Add-On. **Changes take effect within an hour.**
 
 <Frame>
 ![remoteSettingsTab](/images/remoteSettingsTab.png)
@@ -67,7 +67,7 @@
 For example, you can sample 1% of all sessions globally, but capture 100% of SDK initializations where `checkout_error` fires or where users land on your pricing page.
 
 <Note>
   URL-based rules are evaluated using page view events (`$mp_web_page_view`) emitted while heatmap capture is active. These page views are **exempt from event and MTU billing**, so adding URL conditions does not increase your billable event volume. See [Heatmaps for Web](/docs/session-replay/heatmaps) for related click-exemption rules.
 </Note>
 
 <Frame>
@@ -80,19 +80,19 @@
 By default, replays are stored for 30 days after the time of ingestion. Once a replay is expired, there is no way to view that replay. Enterprise plan customers with the paid session replay add-on can customize this retention period between 7 days and 360 days. For more information, reach out to your Account Manager or our sales team.
 </Note>
 
 Session Replay is particularly valuable for understanding user frustration and identifying problematic user experiences. To find relevant replays, you can focus on interesting users (power users, purchases), interesting trends (KPIs spikes or dips), or replays where certain events or sentiment signals (like [dead clicks](/docs/tracking-methods/autocapture#dead-clicks)/[rage clicks](/docs/tracking-methods/autocapture#rage-clicks)) occur.
 
 There are several ways to find and watch replays in Mixpanel:
 
 1. From the Session Replay home
 2. From Mixpanel reports
 3. From User profile pages
 
 ### From the Session Replay Home
 
 Select **Session Replay** from the side navigation in your Mixpanel project. Here, you'll see your most recent replays and can easily filter them by events, properties, or custom time ranges to focus on the replays that matter most to you. Pro tip: when getting started with implementing Session Replay, you can use this view to check if replays are coming in as expected.
 
 ### From Mixpanel Reports
 
 <Note>
   Reports entry point is currently supported for Event, Funnel, and User Profile metrics only.
@@ -122,7 +122,7 @@
 
 ### Replay Feed
 
 The Replay Feed on the left side of the player lets you browse and find replays. It works out of the box with the Mixpanel events and properties you already track (including server-side events) — no extra setup required. Each cell represents a single user journey: a group of replays for a specific user that happened within ~30 minutes of each other. A single journey can contain several replays.
 
 The replay feed allows you to: 
 - Filter by any event, property, or time period
@@ -153,7 +153,7 @@
 
 #### Activity Feed
 
 The Activity Feed tab shows a chronological feed of all events that occurred during the session, including Mixpanel track events, console logs, and network calls. You can search and filter events by type, and click any event to see its details and jump the replay to that moment.
 
 ##### Console Logs
 
@@ -177,7 +177,7 @@
 
 Magic Playlists allow you to save playlists of replays based on events or properties, making it easy to revisit groups of replays that matter to you over time. A playlist stores your filter criteria (events, recording properties, date range, sort order) and can also hold up to 200 individually bookmarked replays. Key capabilities include:
 
 - **Dynamic playlists**: Create playlists based on your Mixpanel events and properties that automatically update as new replays meet your criteria
 - **Bookmarked replays**: Pin specific replays to a playlist so you can easily return to them later
 - **AI-powered insights**: Get AI text summaries that identify key patterns and insights across numerous replays at once
 
@@ -187,7 +187,7 @@
 
 ### Creating a Playlist
 
 1. Access Session Replay from the side navigation in your Mixpanel project
 2. Apply filters based on events, properties, or custom time ranges
 3. Click **Save Playlist** in the header and add a name
 4. Click **Save**
@@ -211,14 +211,14 @@
 
 Use the bookmark filter toggle in the playlist header to show only bookmarked replays. When this filter is active, other filters are disabled. Bookmarked replays appear in a dedicated section at the top of the playlist.
 
 Expired bookmarked replays appear in a separate **Expired Journeys** section. You can remove expired bookmarks, but expired replay content can no longer be played. Bookmark lookback searches up to 365 days.
 
 ## Best Practices
 
 Session Replay is a powerful way to understand and debug user behavior by showing exactly what users see on their screens. This visibility is core to its value—but also introduces inherent privacy and security risks, especially when sensitive information appears in the UI.
 
 Mobile platforms add some unique challenges:
 - SDKs are installed directly on end-user devices, making them harder to roll back or patch quickly.
 - Android’s fragmented ecosystem demands broader testing across different devices and OS versions.
 
 These risks are common across all session replay tools, but well-established industry practices exist to help mitigate them. With careful planning and the right safeguards, teams can more confidently use session replay to improve their products.
@@ -227,9 +227,9 @@
 
 | **Key Considerations**             | **Why It Matters**                                                                   |
 | ------------------------------ | ------------------------------------------------------------------------------------ |
 | **Industries**                 | Apps in healthcare, fintech, or other regulated spaces carry higher compliance risk. |
 | **Sensitive Screens**          | Checkout, payment, and profile screens often contain sensitive user data.            |
 | **Embedded Webviews**          | Embedded web views may require additional review to ensure expected behavior. |
 | **Uncommon App Architectures** | Custom or non-standard implementations may require additional testing and configuration.     |
 
 ---
@@ -243,7 +243,7 @@
 
 ### Performance Considerations
 
 Our Session Replay SDKs are designed with performance in mind, utilizing optimized capture algorithms that reduce CPU and memory usage. However, as with any SDK integration, there may still be some risk of performance impacts. We recommend thorough testing and monitoring your app's performance during initial deployment.
 
 ### Incident Handling
 
@@ -272,21 +272,36 @@
 #### What happens when I reach my Session Replay limit?
 Customers who have purchased the Session Replay add-on will be billed for replays ingested beyond the purchased amount at your per-unit rate. Customers using Session Replay without purchasing the add-on (e.g., those using complimentary replays included with the Free, Growth, or Enterprise plans) will be unable to view replays once they reach the data allowance, unless they upgrade. We will send email notifications to [organization Owners and Billing Admins](/docs/orgs-and-projects/roles-and-permissions#organization-roles) as your projects approaches the data allowance of your subscription plan.
 
 Mixpanel reserves the right to stop ingesting replays once a customer collects replays beyond their purchased/allocated amount. To minimize disruption to your team, we recommend monitoring your data usage in the organization settings and working with your Account Manager (if applicable) to ensure you have the right plan for your needs.
 
 #### How soon are Replays available for viewing after a session begins?
 
 Replays are available for viewing in Mixpanel ~1 minute after the recording is captured.
 
+#### What defines a single replay?
+
+A replay is a continuous recording of a single user's activity. 
+
+On the web, a replay ends after 30 minutes of inactivity (a new replay begins automatically when the user is active again) or once it reaches a maximum length of 24 hours, whichever comes first. Both thresholds are configurable via the `record_idle_timeout_ms` (default 30 minutes) and `record_max_ms` (default 24 hours) [JavaScript init options](/docs/tracking-methods/sdks/javascript/javascript-replay#init-options). On the web, a replay is scoped to a single browser tab or window. Recording continues across page loads and navigations within that same tab (SDK v2.61.0+), but each additional tab or window is recorded as its own replay, as is activity in a different browser or on a different device. A single user's activity across multiple tabs, browsers, or devices is therefore captured as multiple replays, not one.
+
+On our mobile SDKs (iOS, Android, and React Native), you control capture with a sampling rate and by starting or stopping recording manually, just as you can on the web. A replay ends when the user leaves the app. 
+
+{/* ============================================================ */}
+{/* ⚠️ DO NOT REMOVE OR MODIFY the replay definition below.       */}
+{/* We are contractually/legally required to maintain it.        */}
+{/* Before any change, confirm with the PM for Session Replay    */}
+{/* AND Legal (contract implication review). — DJ, 2026-07-09    */}
+{/* ============================================================ */}
+
 #### How long are replays stored?
 
 By default, replays are stored for 30 days after the time of ingestion. Once a replay is expired, there is no way to view that replay. Enterprise plan customers with the paid session replay add-on can customize this retention period between 7 days and 360 days. For more information, reach out to your Account Manager or our sales team.
 
 #### Why does it say the player failed to load?
 
 To maintain a high level of security, Mixpanel runs your session replays in an isolated domain through an iframe. Occasionally, this domain may be blocked by an ad blocker or specific browser settings. We recommend disabling any ad blockers, or whitelisting the Mixpanel domain.
 
 For extensions like uBlock, go to "My Filters" in the extension settings and add the following custom filter:
 
 ```
 @@||mxpnl.com^$domain=mxpnl.com
@@ -298,23 +313,23 @@
 
 #### Can I use Session Replay with a CDP?
 
 You can use Session Replay with CDPs (e.g., Segment and mParticle) on both web and mobile.
 
 | Platform | Guidance |
 | --- | --- |
 | Web | Your app must include the Mixpanel Javascript SDK, with Session Replay enabled. Learn more in the developer guide [here](/docs/tracking-methods/sdks/javascript/javascript-replay#session-replay-with-a-cdp). |
 | iOS | Works with CDPs, but you must install the Mixpanel Session Replay SDK in your app. Read more in our [iOS implementation guide](/docs/tracking-methods/sdks/swift/swift-replay). |
 | Android | Works with CDPs, but you must install the Mixpanel Session Replay SDK in your app. Read more in our [Android implementation guide](/docs/tracking-methods/sdks/android/android-replay). |
 
 #### How does Session Replay work differently on web versus mobile?
 
 Session Replay works differently on web versus mobile in Mixpanel:
 - **Web**: Captures DOM changes to reconstruct user interactions, tracking elements, clicks, and navigation. This provides an event-based replay of user activity.
 - **Mobile**: Captures actual screen pixels since native apps don't use a DOM. This visual approach records all on-screen activity as it appears to users, including scrolls, carousels, and auto-scrolling elements.
 
 #### How can I estimate how many Replays I will generate?
 
 If you already use Mixpanel, the [Session Start events](/docs/features/sessions) are a way to estimate the rough amount of replays you might expect. This is especially true if you use timeout-based query sessions. However, because our sessions are defined at query time, we cannot guarantee these metrics will be directly correlated.
 
 When you enable Session Replay, use the above proxy metric to determine a starting sampling percentage, which will determine how many replays will be sent. You can always adjust this as you go to calibrate to the right level.
 
@@ -324,4 +339,4 @@
 
 #### Can I record cross-origin iframes within my page?
 
 Yes, Session Replay supports recording cross-origin iframes embedded within your page (Web only, SDK v2.77.0+). Both the parent page and child iframe must have the Mixpanel SDK initialized with `record_allowed_iframe_origins` configured to include each other's origins. For detailed setup instructions, see [Cross-Origin Iframe Recording](/docs/tracking-methods/sdks/javascript/javascript-replay#cross-origin-iframe-recording).