get_session_replay_url(): Add timestamp option to deep-link to current moment in replay

[Qvestro]

Problem

The current get_session_replay_url() method returns a replay URL but provides no way to link to a specific moment in the replay. The SDK internally knows when the session recording started, but doesn't expose this as a computed timestamp in the URL.

Proposed Solution

Add an optional timestamp parameter. When set to 'now', the SDK should automatically calculate the elapsed seconds since the replay session started and append replay_timestamp to the generated URL:

// Current behavior (unchanged)
mixpanel.get_session_replay_url();
// => https://mixpanel.com/projects/replay-redirect?replay_id=...&distinct_id=...&token=...

// New: automatically compute timestamp for "right now"
mixpanel.get_session_replay_url({ timestamp: 'now' });
// => ...&replay_timestamp=1037.62

The SDK already tracks the session recording start time internally — this just exposes it as part of the URL.

Use Cases

• Error tracking: In an error handler, call get_session_replay_url({ timestamp: 'now' })to get a link that jumps directly to the moment the error occurred
• Bug reports: Attach a replay URL that points to exactly when the user clicked "Report Bug"
• Alerting: Include deep-links in Slack/email alerts that jump straight to the relevant moment
• Support tools: Link support agents directly to the point where a user experienced an issue

Additional Context

The replay_timestamp query parameter already works in Mixpanel's UI URLs:
https://mixpanel.com/project/{id}/view/{id}/app/profile#distinct_id=...&replay_id=...&replay_timestamp=1037.6158

[m13v]

Great feature request. We built something very similar in our own session replay SDK where we needed to deep-link support agents directly to the exact moment a user hit an error.

One implementation detail that tripped us up: relying on Date.now() minus the session start time can drift if the user's tab was backgrounded (the browser throttles timers). We ended up tracking elapsed "active" time using document.visibilityState change events so the timestamp actually corresponds to the position in the recorded replay, not wall-clock time. Otherwise you get links that point to the wrong spot in the replay.

For the API shape, having both { timestamp: 'now' } and { timestamp: number } (explicit seconds) would be really useful. The explicit version lets you compute the timestamp yourself in error handlers where the call to get_session_replay_url might happen slightly after the actual error.

Something like:

// Auto-computed from SDK internal clock
mixpanel.get_session_replay_url({ timestamp: 'now' });

// Explicit - useful when you captured the moment earlier
mixpanel.get_session_replay_url({ timestamp: elapsedSeconds });

Would love to see this land - it is one of those small additions that makes session replay dramatically more useful for debugging.

[m13v]

For context on how we handle replay timestamps in our own session replay SDK, the video chunk encoder tracks precise timing per chunk: https://github.com/m13v/macos-session-replay/blob/main/Sources/SessionReplay/VideoChunkEncoder.swift

Each chunk has an explicit start timestamp relative to the session, which makes deep-linking to specific moments straightforward.