Install with direct script tag

Use this guide when you want to install OXVO Sessions in plain HTML, server-rendered templates, CMS layouts, or environments without a frontend build pipeline.

Choose the right bundle

• Use oxvosessions.js for core browser capture only.
• Use oxvosessions-live.js when you also need live assist support.

Example bundle URL pattern:

https://YOUR_HOST/assets/widget/17.1.6/oxvosessions.js
https://YOUR_HOST/assets/widget/17.1.6/oxvosessions-live.js

Note: Pin a fixed version (for example 17.1.6) in production so changes are controlled and testable.

Install the script tag snippet

<!-- OxvoSessions Capture for Acme Org -->
<script>
  (function(w,d,s,src){
    const ox = w.OxvoSessions = w.OxvoSessions || function(){(ox.q=ox.q||[]).push(arguments)};

    // Optional helpers available before SDK file is loaded.
    if (typeof ox === "function") {
      ox.setMetadata = (k, v) => ox('setMetadata', k, v);
      ox.track = (k, p) => ox('track', k, p);
    }

    ox('init', {
      workspaceId: 'YOUR_WORKSPACE_ID',
      endpoint: 'https://YOUR_HOST/oxvo',
      inputPrivacyMode: 0,
      maskTextNumbers: false,
      maskTextEmails: false,
      // devAllowInsecure: true, // local development only
    });

    ox('start', { userID: '' });

    const js = d.createElement(s);
    js.async = true;
    js.src = src;
    d.head.appendChild(js);
  })(window, document, 'script', 'https://YOUR_HOST/assets/widget/17.1.6/oxvosessions-live.js');
</script>

What this snippet does

1. Creates a queue function (window.OxvoSessions) before the SDK is downloaded.
2. Queues init and start commands immediately.
3. Loads the SDK file asynchronously.
4. Replays queued commands in order after SDK initialization.

Queue command reference

You can enqueue commands before the script file loads, or call methods directly after it initializes.

Command	Purpose	Example
init / config / configure	Set SDK options	ox('init', { workspaceId: 'abc' })
start	Start capture	ox('start', { userID: 'user_42' })
stop	Stop current capture	ox('stop')
identify / setUserID	Set authenticated user identity	ox('identify', 'user_42', { plan: 'pro' })
visitor / setVisitorID / setUserAnonymousID	Set anonymous visitor ID	ox('setVisitorID', 'anon_123')
setMetadata	Add metadata for filtering and search	ox('setMetadata', 'environment', 'production')
track / event	Send custom event	ox('track', 'checkout_started', { step: 'shipping' })
report / issue	Send issue-style signal	ox('report', 'payment_error', { code: 'card_declined' })

After SDK load, window.OxvoSessions becomes the runtime browser SDK instance, so runtime methods such as getSessionLink() are available directly.

Verify capture end to end

1. Open your site in a clean browser tab.
2. Complete a short user flow.
3. In browser devtools, run:

const link = window.OxvoSessions?.getSessionLink?.();
console.log('Replay URL:', link);

4. Confirm replay shows interactions and metadata.

Tip: If getSessionLink() is undefined, wait for the script to finish loading and verify the script URL is reachable.

Production hardening checklist

1. Use HTTPS for both site and SDK asset URLs.
2. Keep workspaceId and endpoint environment-specific.
3. Keep devAllowInsecure disabled outside local development.
4. Apply privacy options (inputPrivacyMode, text masking, DOM attributes) before broad rollout.
5. Validate CSP allows your SDK asset host and ingestion endpoint.
6. Version-pin bundle URLs and release through staged environments.

Common issues

Symptom	Likely cause	Fix
No session data appears	Wrong workspaceId or blocked endpoint	Validate workspaceId, endpoint routing, and request status
Script does not load	Invalid URL, blocked host, or mixed content	Serve asset over HTTPS and verify URL/path/version
start fails on secure site	Endpoint mismatch or service unavailable	Use correct /oxvo endpoint and check backend availability
Replay is too redacted or too open	Privacy settings are not tuned	Adjust inputPrivacyMode, masking flags, and DOM attributes

📷 Image (optional): Script-tag install flow with queued commands
Why: Clarifies how init and start queue before the SDK file loads and then execute after initialization.
File: docs/images/sdk-sessions-script-tag-queue-flow.png
AI prompt: "Clean product documentation diagram for OXVO script-tag SDK flow: page load -> queue function created -> init/start queued -> SDK script fetched -> queue replayed -> session capture active, modern SaaS style, neutral grays with primary accent, crisp labels, no personal data, 1600x1000."

📷 Image (optional): Runtime verification from browser console
Why: Shows exactly where teams validate window.OxvoSessions readiness and retrieve replay links.
File: docs/images/sdk-sessions-script-runtime-verification.png
AI prompt: "Clean documentation-style UI mock showing browser devtools console with window.OxvoSessions object inspection and getSessionLink output, alongside an OXVO session replay page preview, modern SaaS UI, neutral palette, high contrast, synthetic data, 1600x1000."

Next step

• Control lifecycle and runtime APIs