Documentation

    Session Recording

    AICopy for LLM

    Your on-premise instance can record Sessions and render them to MP4, with the video files never leaving your infrastructure. For recording to work you need:

    1. The session recording feature on your plan. It's embedded in your license key, so if you just added it, re-download the license key (or use the URL form of LICENSE_KEY) and restart the server.
    2. MongoDB (MONGO_URI must not be disabled): Session events used for the replay are stored there.
    3. For Sessions that include browser co-browsing, a separate Chromium container the server can reach over WebSocket, described below.

    Sessions made only of screen sharing frames are rendered with ffmpeg directly and don't need the Chromium container (if you run the binaries instead of Docker, make sure ffmpeg is available on the PATH).

    The Chromium Container

    Browser co-browsing Sessions are replayed in a real browser. Use our upscope/chromium image:

    docker run -d -e TOKEN=mytoken -p 3000:3000 upscope/chromium

    Then point your Co-Browsing API instance at it with CHROMIUM_ENDPOINT=ws://yourdockerhost:3000?token=mytoken.

    The container is configured through environment variables:

    Environment VariableDescriptionDefault
    TOKENThe shared secret used to authenticate connections, passed in the endpoint's ?token= query. When unset, authentication is disabled entirely.(nil)
    PORTThe port the container listens on.3000
    POOL_MINThe number of browsers kept warm and ready.1
    POOL_MAXThe maximum number of concurrent browsers. Past this, requests queue.10
    QUEUE_MAX_WAITHow long a request waits for a free browser before failing, in milliseconds.8000
    TIMEOUTThe maximum lifetime of a single browser session, in milliseconds.3600000
    GOTO_TIMEOUTThe navigation timeout for the container's /screenshot and /pdf HTTP endpoints, in milliseconds. Not used for Session replays.10000
    SHUTDOWN_GRACEHow long in-flight work gets to finish after SIGTERM before the process exits, in milliseconds.10000
    LOG_CONNECTIONSLog a line for each new connection from your Co-Browsing API instance. Set to false to disable.true
    STATS_INTERVAL_MSThe interval of the periodic pool and load stats log line, in milliseconds. 0 disables it.60000
    DEBUGDebug log namespaces, e.g. upscope:*.(nil)
    Fonts in Replays
    The image ships metric-compatible substitutes for the fonts most commonly captured in Sessions (Segoe UI, SF Pro, Apple Color Emoji, and others), so replays match what the Visitor saw. If you have a license for the real fonts, mount them at /usr/share/fonts/custom and the container picks them up on start.

    Requesting a Recording

    Nothing is rendered until you ask for it. Once a Session has ended, POST its session_id to {BASE_ENDPOINT}/api/recordings/{visitor_short_id}, authenticated with a short-lived HS256 token signed with your SECRET_KEY. The first call starts the render, later calls report progress, and the video URL comes back once it's ready. See Requesting a Session Recording for the full request and its responses.

    A Session can't be rendered if no events were stored for it, if it needs a browser and CHROMIUM_ENDPOINT is unset, or if MongoDB is disabled.

    You can skip recording an individual Session with the session_properties.record parameter on the watch link and viewer token endpoints.

    Storing Recordings

    Recordings can be stored on a local volume (the default), on Amazon S3, on Azure Blob Storage, or on Google Cloud Storage:

    Environment VariableDescriptionDefault
    RECORDINGS_STORAGEvolume stores recordings on disk under /recordings (mount a volume there to persist them) and serves them from {BASE_ENDPOINT}/recordings; s3, azure and gcs upload them to Amazon S3, Azure Blob Storage and Google Cloud Storage respectively.volume
    RECORDINGS_S3_BUCKETThe S3 bucket recordings are uploaded to when using s3 storage. Falls back to S3_BUCKET.(nil)
    ACCESS_KEY_ID, SECRET_ACCESS_KEY, AWS_REGIONThe AWS credentials used for s3 storage.(nil)
    RECORDINGS_AZURE_CONTAINERThe blob container recordings are uploaded to when using azure storage. Falls back to AZURE_CONTAINER.(nil)
    AZURE_STORAGE_CONNECTION_STRINGThe storage account connection string used for azure storage.(nil)
    RECORDINGS_GCS_BUCKETThe Cloud Storage bucket recordings are uploaded to when using gcs storage. Falls back to GCS_BUCKET.(nil)
    GCP_CREDENTIALS_JSONThe service account key JSON used for gcs storage.(nil)
    RECORDINGS_BASE_URLThe public base URL recording links point to. Set it when using cloud storage (your bucket, container or CDN URL).{BASE_ENDPOINT}/recordings
    CHROMIUM_ENDPOINTWebSocket endpoint of the Chromium container used to replay browser Sessions. When unset, only screen sharing Sessions can be recorded.(nil)
    RENDER_RECORD_ENDPOINTThe URL the Chromium container loads to render the replay. Override it when your BASE_ENDPOINT is not reachable from that container.{BASE_ENDPOINT}/record

    Recording file URLs are not guessable (they contain a UUID), matching the access model of our cloud storage.