Skip to main content

​
Session Recording API

Pingtree’s Session Recording feature captures user interactions on your landing pages and form flows in real time. Recordings can be replayed later for quality assurance, compliance auditing, conversion optimization, and dispute resolution.

​
What is Session Recording?

Session Recording is powered by rrweb, an open-source library that captures a full, pixel-accurate replay of everything a user does on a page — mouse movements, clicks, scrolling, form input, and more. Each recording is tied to a specific lead transaction so you can correlate a replay with the exact lead record. Recordings are streamed to the Pingtree backend every 3 seconds and stored server-side, then uploaded to S3 for long-term retention and replay access.

​
How It Works

  1. When a user lands on a campaign page where Session Recording is enabled, the browser loads the rrweb recording script.
  2. The recorder calls POST /recording/initialize to create a new session and receive a unique sessionId.
  3. The sessionId is stored in sessionStorage with a 10-minute expiry, so the same session is reused across page navigations within the same tab.
  4. Recorded events are batched and sent to POST /recording/store_events every 3 seconds, encoded as Base64.
  5. When the user completes or exits the form flow, a final flush sends any remaining events.
  6. The backend merges the incoming events with any previously stored events for the same session, building a complete replay file.

​
Enabling Session Recording

Session Recording is configured at the Campaign level. Configuration Path: Campaign > Single View > Integrations Tab > Session Recording

​
Prerequisites

  • Your advertiser account must have a sufficient wallet balance. The system checks your balance before initializing each new recording.
  • A per-recording cost (sessionRecordingCost) is deducted from your balance the first time a recording is initialized for a given transaction. Subsequent event flushes for the same transaction are free.

​
Configuration Options

OptionDescription
Enable Session RecordingToggle to activate session recording for this campaign. When enabled, the rrweb script is automatically injected into your campaign’s landing pages and form flows.
API KeyNot required — session recording uses Pingtree’s internal infrastructure. No third-party API key is needed.
Note: The recording script is only injected when billing is enabled and your account has a positive balance. If your balance is zero or your account is blocked, the script is silently skipped and no recording takes place.

​
API Endpoints

These endpoints are used internally by the Pingtree recording script. You do not need to call them directly.

​
POST /recording/initialize

Initializes a new recording session. Request body:
FieldTypeDescription
urlstringThe current page URL being recorded.
cidstringThe campaign unique ID.
transactionIdstringThe lead transaction ID.
Response: 
{
  "type": "success",
  "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

​
POST /recording/store_events

Stores a batch of recorded events for an active session. Request body:
FieldTypeDescription
sessionIdstringThe session ID returned by /initialize.
encodedStringstringBase64-encoded JSON array of rrweb event objects.
Events from multiple calls are merged into a single replay file per session.

​
Recorded Data

Each session recording stores the following metadata alongside the event replay:
FieldDescription
recordingIdUnique session identifier (UUID).
transactionIdThe lead transaction this recording belongs to.
cidThe campaign ID.
urlThe page URL where recording started.
userIpThe visitor’s IP address.
browserBrowser and user agent details.
hasRecordingtrue once at least one event batch has been stored.
isUploadedtrue once the recording has been uploaded to S3 for long-term storage.

​
Usage and Billing

  • A cost is deducted from your advertiser balance once per unique transaction (i.e., per lead), not per event batch.
  • Campaign-level counters (apiUsageCount.session) track total recordings, monthly recordings, and associated costs.
  • You can monitor recording usage in your campaign reporting dashboard.

​
Use Cases

  • Compliance Auditing: Replay exactly what a user saw and did when submitting a lead, useful for TCPA and consent-related disputes.
  • Conversion Optimization: Identify where users drop off in your form flows and improve the experience.
  • Quality Assurance: Spot bot-like behavior or suspicious form interactions in your lead data.
  • Dispute Resolution: Provide a timestamped, verifiable replay of a user session to resolve advertiser or publisher disputes.
Tip: Combine Session Recording with TrustedForm or eConsent to build a robust compliance and consent documentation stack for each lead.