Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/background-capture-mask-lag.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'posthog-ios': patch
---

With `screenshotModeBackgroundCapture` on, session replay masks drifting content over the position its pixels can trail to, and skips frames captured while the screen scrolls or animates, or while a masked cell is recycled, instead of uploading them with misaligned masks.
60 changes: 35 additions & 25 deletions PostHog/Replay/PostHogMaskSettleAnalysis.swift
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,12 @@
/// invalidating them.
static let settleWindowSeconds: TimeInterval = 0.025

/// Gap between the first mask sample and the off-main background render. On device, a render
/// taken right after an abrupt scroll stop still showed the pre-stop position; a still
/// verdict must span longer than that lag. 25ms already avoided it in testing, so this
/// leaves margin for slower devices.
static let backgroundCaptureLeadSeconds: TimeInterval = 0.1

/// At or below 80pt/s, geometry counts as unmoved and rects are used exactly as sampled.
/// Raise only to stop idle screens paying for inflation, and only a little: this much
/// displacement then goes uncompensated, so it is the one knob that trades directly
Expand Down Expand Up @@ -111,35 +117,39 @@
return oldRects
}

/// Per-owner union of two samples taken either side of a render: covers wherever the
/// content sat while the render ran. An owner present in only one sample was still on
/// screen for part of that window, so its rect is emitted as collected rather than
/// discarding the frame β€” a scroll that recycles cells changes the owner set constantly,
/// and dropping every such frame freezes the recording across the whole interaction.
/// Unlike `pairedOldRects` the result is a mask list, not positionally tied to `after`.
/// nil only for a repeated owner within one sample, where the pairing is genuinely
/// ambiguous and there is no safe rect to emit.
static func sweptRects(before: [MaskedRegion]?, after: [MaskedRegion]?) -> [CGRect]? {
guard let before, let after, let beforeByOwner = rectsByOwner(before) else {
/// Masks for a frame rendered off-main between two samples, or nil to skip the frame.
/// The off-main render copies the last committed frame, which can trail `before`, so
/// drifted masks take `settleVerdict`'s inflation, including its trail behind `before`.
/// Motion, an unpaired owner (a cell recycled mid-render), or a nil sample skips the frame:
/// no rect is known to cover where that content sat when the pixels were committed, and
/// the presentation-tree renderer the settled path falls back to is main-only.
static func backgroundCaptureMaskRects(before: [MaskedRegion]?, after: [MaskedRegion]?) -> [CGRect]? {
let verdict = settleVerdict(before: before, after: after)
switch verdict.band {
case .still:
// Within tolerance, but the pixels may still show `before`.
guard let after, let oldRects = pairedOldRects(before: before, after: after) else { return nil }
return zip(oldRects, after).map { $0.union($1.rect) }
case .drift:
return verdict.inflatedRects
case .motion:
return nil
}
}

var rects: [CGRect] = []
rects.reserveCapacity(max(before.count, after.count))
var seenAfterOwners: Set<ObjectIdentifier> = []
seenAfterOwners.reserveCapacity(after.count)
for region in after {
guard seenAfterOwners.insert(region.owner).inserted else {
return nil
}
// No counterpart means the owner appeared mid-render; cover where it landed.
rects.append(beforeByOwner[region.owner].map { $0.union(region.rect) } ?? region.rect)
}
// Owners that went away mid-render were still displayed for part of it.
for region in before where !seenAfterOwners.contains(region.owner) {
rects.append(region.rect)
/// Three-sample form: `lead` is taken `backgroundCaptureLeadSeconds` before `before`, so a
/// still span covers the render's lag, while `before` stays adjacent to the render and
/// catches anything that moved, appeared or vanished during the wait. Each consecutive
/// pair must be coverable on its own; the masks are the union of both.
static func backgroundCaptureMaskRects(
lead: [MaskedRegion]?, before: [MaskedRegion]?, after: [MaskedRegion]?
) -> [CGRect]? {
guard let leading = backgroundCaptureMaskRects(before: lead, after: before),
let trailing = backgroundCaptureMaskRects(before: before, after: after)
else {
return nil
}
return rects
return leading + trailing
}

/// Banded by measured drift:
Expand Down
56 changes: 44 additions & 12 deletions PostHog/Replay/PostHogReplayIntegration.swift
Original file line number Diff line number Diff line change
Expand Up @@ -1626,16 +1626,46 @@
)
}

/// The render sits between two mask samples instead of one: measure geometry, render
/// off-main, measure again, mask the per-owner union β€” provably covering wherever the
/// content sat while the render ran, so no threshold is needed. Always uses
/// `drawHierarchy`, never the presentation-tree renderer: that reads `layer.presentation()`,
/// which is main-only, and this path's other reads already sit inside `main.sync`.
/// Three mask samples around an off-main render: measure geometry, wait
/// `backgroundCaptureLeadSeconds`, measure again, render, measure a third time, then mask as
/// `backgroundCaptureMaskRects` decides β€” swept and trailed when the content drifted,
/// skipped on motion, an unpaired owner, or a missing sample. Always uses `drawHierarchy`,
/// never the presentation-tree renderer: that reads `layer.presentation()`, which is
/// main-only, and this path's other reads already sit inside `main.sync`.
private func scheduleBracketedBackgroundCapture(window: UIWindow, screenName: String?, postHog: PostHogSDK) {
var lead = collectMaskedRegions(in: window)
guard lead != nil else {
finishScreenshotRender()
return
}
PostHogReplayIntegration.dispatchQueue.asyncAfter(deadline: .now() + Self.backgroundCaptureLeadSeconds) { [weak self] in
Comment thread
turnipdabeets marked this conversation as resolved.
Resolved
guard let self else {
DispatchQueue.main.async { lead = nil }
return
}
self.performBracketedBackgroundCapture(window: window, lead: &lead, screenName: screenName, postHog: postHog)
}
Comment thread
turnipdabeets marked this conversation as resolved.
Resolved
}

/// `lead` is inout so it can be dropped on main: MaskedRegion retains its view, and a view's
/// last release (with its UIKit teardown) must not run on the replay queue.
@discardableResult
private func performBracketedBackgroundCapture(window: UIWindow, screenName: String?, postHog: PostHogSDK) -> Bool {
private func performBracketedBackgroundCapture(
window: UIWindow, lead: inout [MaskedRegion]?, screenName: String?, postHog: PostHogSDK
) -> Bool {
defer { finishScreenshotRender() }

guard let before = DispatchQueue.main.sync(execute: { self.collectMaskedRegions(in: window) }) else {
var before = DispatchQueue.main.sync { () -> [MaskedRegion]? in
let sample = self.collectMaskedRegions(in: window)
// The lead pair alone decides most motion frames; skip them before paying for a render.
guard Self.backgroundCaptureMaskRects(before: lead, after: sample) != nil else {
lead = nil
hedgeLog("[Session Replay] Skipping snapshot: mask geometry could not be covered during background capture")
return nil
}
return sample
}
guard before != nil else {
return false
Comment thread
turnipdabeets marked this conversation as resolved.
Resolved
}
// Off-main on purpose, and the reason this mode exists: drawHierarchy on main was too
Expand All @@ -1644,9 +1674,13 @@
// aligned with pixels despite the render happening on this thread.
let image = window.toImage(preferFidelityRenderer: true)
let capture = DispatchQueue.main.sync { () -> ScreenshotCapture? in
defer {
lead = nil
before = nil
}
let after = self.collectMaskedRegions(in: window)
guard let rects = Self.sweptRects(before: before, after: after) else {
hedgeLog("[Session Replay] Skipping snapshot: mask samples could not be paired")
guard let rects = Self.backgroundCaptureMaskRects(lead: lead, before: before, after: after) else {
hedgeLog("[Session Replay] Skipping snapshot: mask geometry could not be covered during background capture")
return nil
}
// No renderer preference: `renderImage: false` means this call never renders β€” the
Expand Down Expand Up @@ -1727,9 +1761,7 @@
}

if postHog.config.sessionReplayConfig.screenshotModeBackgroundCapture {
PostHogReplayIntegration.dispatchQueue.async { [weak self] in
self?.performBracketedBackgroundCapture(window: window, screenName: screenName, postHog: postHog)
}
scheduleBracketedBackgroundCapture(window: window, screenName: screenName, postHog: postHog)
} else {
scheduleSettledCapture(window: window, screenName: screenName, postHog: postHog)
}
Expand Down
135 changes: 60 additions & 75 deletions PostHogTests/PostHogMaskScenarioTest.swift
Original file line number Diff line number Diff line change
Expand Up @@ -498,115 +498,100 @@
#expect(inflated[0].maxY >= 125.31)
}

@Test("swept union covers both sample positions, in after order")
func sweptRectsCoversBothSamplesInAfterOrder() throws {
@Test("background capture masks the trail behind the older sample")
func backgroundCaptureCoversTrailBehindBefore() throws {
let a = NSObject()
let b = NSObject()
let before = [
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
region(b, CGRect(x: 0, y: 100, width: 100, height: 20)),
]
// b moves; a is stationary. after is in swapped order vs before, so
// ordering must be recovered from `owner`, not index.
let after = [
region(b, CGRect(x: 0, y: 130, width: 100, height: 20)),
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
]
let swept = try #require(PostHogReplayIntegration.sweptRects(before: before, after: after))
#expect(swept.count == 2)

// swept[0] pairs with after[0] (b): union of y=100..120 and y=130..150.
#expect(swept[0] == CGRect(x: 0, y: 100, width: 100, height: 50))

// swept[1] pairs with after[1] (a): stationary, so it collapses to a's rect.
#expect(swept[1] == CGRect(x: 0, y: 0, width: 100, height: 20))
}
let before = [region(a, CGRect(x: 0, y: 100, width: 100, height: 20))]
let after = [region(a, CGRect(x: 0, y: 105, width: 100, height: 20))]
let rects = try #require(PostHogReplayIntegration.backgroundCaptureMaskRects(before: before, after: after))

@Test("nil before makes sweptRects nil")
func sweptRectsNilBefore() {
let a = NSObject()
let after = [region(a, CGRect(x: 0, y: 0, width: 100, height: 20))]
#expect(PostHogReplayIntegration.sweptRects(before: nil, after: after) == nil)
// The off-main render can copy pixels committed before `before` was sampled, here at
// y=95; a union of the two samples alone would leave y=95..100 visible.
#expect(rects.count == 1)
#expect(rects[0].contains(CGRect(x: 0, y: 95, width: 100, height: 30)))
}

@Test("nil after makes sweptRects nil")
func sweptRectsNilAfter() {
@Test("background capture skips a frame whose cell was recycled mid-render")
func backgroundCaptureSkipsRecycledOwner() {
let a = NSObject()
let b = NSObject()
let before = [region(a, CGRect(x: 0, y: 0, width: 100, height: 20))]
#expect(PostHogReplayIntegration.sweptRects(before: before, after: nil) == nil)
let after = [region(b, CGRect(x: 0, y: 200, width: 100, height: 20))]
// Where `a` sat when the pixels were committed was never sampled.
#expect(PostHogReplayIntegration.backgroundCaptureMaskRects(before: before, after: after) == nil)
}

@Test("an owner that appears mid-render is covered, not dropped")
func sweptRectsCountMismatch() throws {
@Test("background capture skips a frame where an owner appeared mid-render")
func backgroundCaptureSkipsAppearedOwner() {
let a = NSObject()
let b = NSObject()
let before = [region(a, CGRect(x: 0, y: 0, width: 100, height: 20))]
let after = [
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
region(b, CGRect(x: 0, y: 100, width: 100, height: 20)),
]
// b appeared mid-render, so it was displayed for part of the window and is covered
// rather than costing the whole frame.
let swept = try #require(PostHogReplayIntegration.sweptRects(before: before, after: after))
#expect(swept == [
CGRect(x: 0, y: 0, width: 100, height: 20),
CGRect(x: 0, y: 100, width: 100, height: 20),
])
#expect(PostHogReplayIntegration.backgroundCaptureMaskRects(before: before, after: after) == nil)
}

@Test("duplicate owner in before makes sweptRects nil")
func sweptRectsDuplicateOwnerInBefore() {
@Test("background capture skips a frame that moved past the drift budget")
func backgroundCaptureSkipsMotion() {
let a = NSObject()
let b = NSObject()
let before = [
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
]
let after = [
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
region(b, CGRect(x: 0, y: 100, width: 100, height: 20)),
]
#expect(PostHogReplayIntegration.sweptRects(before: before, after: after) == nil)
let before = [region(a, CGRect(x: 0, y: 0, width: 100, height: 20))]
let after = [region(a, CGRect(x: 0, y: 200, width: 100, height: 20))]
#expect(PostHogReplayIntegration.backgroundCaptureMaskRects(before: before, after: after) == nil)
}

@Test("background capture skips a frame with a missing sample")
func backgroundCaptureSkipsNilSample() {
let sample = [region(NSObject(), CGRect(x: 0, y: 0, width: 100, height: 20))]
#expect(PostHogReplayIntegration.backgroundCaptureMaskRects(before: nil, after: sample) == nil)
#expect(PostHogReplayIntegration.backgroundCaptureMaskRects(before: sample, after: nil) == nil)
}

@Test("duplicate owner in after makes sweptRects nil")
func sweptRectsDuplicateOwnerInAfter() {
@Test("background capture masks both samples of a still frame, paired by owner")
func backgroundCaptureStillCoversBothSamples() throws {
let a = NSObject()
let b = NSObject()
let before = [
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
region(b, CGRect(x: 0, y: 100, width: 100, height: 20)),
]
// a moves 1pt, within the still tolerance; after is in swapped order.
let after = [
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
region(a, CGRect(x: 0, y: 0, width: 100, height: 20)),
region(b, CGRect(x: 0, y: 100, width: 100, height: 20)),
region(a, CGRect(x: 0, y: 1, width: 100, height: 20)),
]
#expect(PostHogReplayIntegration.sweptRects(before: before, after: after) == nil)
let rects = try #require(PostHogReplayIntegration.backgroundCaptureMaskRects(before: before, after: after))
#expect(rects == [
CGRect(x: 0, y: 100, width: 100, height: 20),
CGRect(x: 0, y: 0, width: 100, height: 21),
])
}

@Test("a fully recycled owner set covers both samples, not nil")
func sweptRectsDisjointOwnerSet() throws {
@Test("background capture skips content that moved during the lead wait and came back")
func backgroundCaptureSkipsBounceDuringLead() {
let a = NSObject()
let b = NSObject()
let before = [region(a, CGRect(x: 0, y: 0, width: 100, height: 20))]
let after = [region(b, CGRect(x: 0, y: 200, width: 100, height: 20))]
// Neither owner can be paired, but both were on screen during the render window:
// `after` entries come first, then the ones that went away.
let swept = try #require(PostHogReplayIntegration.sweptRects(before: before, after: after))
#expect(swept == [
CGRect(x: 0, y: 200, width: 100, height: 20),
CGRect(x: 0, y: 0, width: 100, height: 20),
])
let lead = [region(a, CGRect(x: 0, y: 0, width: 100, height: 20))]
// Rendered at y=100, back at y=0 by the last sample.
let before = [region(a, CGRect(x: 0, y: 100, width: 100, height: 20))]
let after = [region(a, CGRect(x: 0, y: 0, width: 100, height: 20))]
#expect(PostHogReplayIntegration.backgroundCaptureMaskRects(lead: lead, before: before, after: after) == nil)
}

@Test("background capture skips a private view that appeared during the lead wait and vanished")
func backgroundCaptureSkipsTransientOwner() {
let before = [region(NSObject(), CGRect(x: 0, y: 0, width: 100, height: 20))]
#expect(PostHogReplayIntegration.backgroundCaptureMaskRects(lead: [], before: before, after: []) == nil)
}

@Test("a stationary owner's swept rect equals its rect unchanged")
func sweptRectsStationaryOwnerUnchanged() throws {
@Test("background capture masks every sampled position when all three samples are still")
func backgroundCaptureStillAcrossThreeSamples() throws {
let a = NSObject()
let rect = CGRect(x: 10, y: 20, width: 100, height: 20)
let before = [region(a, rect)]
let after = [region(a, rect)]
let swept = try #require(PostHogReplayIntegration.sweptRects(before: before, after: after))
#expect(swept == [rect])
let lead = [region(a, CGRect(x: 0, y: 0, width: 100, height: 20))]
let before = [region(a, CGRect(x: 0, y: 1, width: 100, height: 20))]
let after = [region(a, CGRect(x: 0, y: 2, width: 100, height: 20))]
let rects = try #require(PostHogReplayIntegration.backgroundCaptureMaskRects(lead: lead, before: before, after: after))
#expect(rects == [CGRect(x: 0, y: 0, width: 100, height: 21), CGRect(x: 0, y: 1, width: 100, height: 21)])
}
}
#endif
Loading
Loading