Docs/Guides/SDK configuration

Guides · SDK

SDK configuration

Complete reference for configuring the Sumidata JavaScript SDK. Control privacy, performance, and behaviour via data-* attributes and the runtime API.

01Basic installation

All configuration lives on the script tag as data-* attributes.

index.html

<script
  src="https://sdk.sumidata.io/loader.js"
  data-project-id="YOUR_PROJECT_ID"
  async></script>

02Configuration options

Every option has a sensible default. Only set what you need to override.

data-project-id (required)

Your unique project identifier from the Dashboard (Settings → Project).

data-project-id="proj_abc123xyz"

data-privacy-level

How aggressively the SDK masks content in session replays.

light — mask passwords and credit card fields only
standard — mask all input fields (default)
strict — mask all text content, including static copy

data-privacy-level="standard"

data-capture-console

Capture console.log / console.error output into the session timeline. Default: true.

data-capture-console="false"

data-capture-network

Capture XHR / Fetch network activity (URL, method, status, timing). Default: true.

data-flush-interval

How often (ms) to flush buffered events, logs, and replay chunks to the server. Lower = more real-time, higher = better batching. Minimum reasonable value is 2000; below that the SDK spends more time on HTTP than on recording. Default: 10000.

Events, logs, and replay chunks share the same flush cycle — a single POST /sdk/ingest carries all three. When the tab is hidden or unloading, the SDK flushes immediately via the Beacon API, so no in-flight data is dropped on page close or OAuth redirect.

data-sample-rate

Percentage of sessions to record (0–100). Useful for high-traffic sites. Default: 100.

03JavaScript API

All runtime methods are safe to call before the SDK has loaded — they queue until ready.

Every runtime method is GTM-style: Sumidata.push('method', [arg1, arg2]). Direct calls like Sumidata.event(...) also work and are identical in effect. The full set of supported methods:

Method	Args	Purpose
`event`	`[name, properties?]`	Track a product event or conversion.
`identify`	`[userId]`	Link the session to a stable user ID. Triggers session rotation if the user changed.
`reset`	`[]`	Clear stored identity and rotate the session. Call on logout.
`identifyExperiment`	`[ [{ id, variant }, …] ]`	Bind A/B variants to the current session. Sticky per session.

Identify users

Stamps the current session and all subsequent events with your stable user ID. If a different user was previously identified on this device, the SDK automatically rotates the session to prevent history merge.

app.js

// At login
Sumidata.push('identify', ['user_123'])

The user ID persists in localStorage across tabs and OAuth redirects. A returning user is auto-identified when a new session starts — you don't need to call identify() again unless the ID changes.

Reset on logout

Clears the stored user ID, rotates the session, and starts a fresh replay. Always call this on logout — otherwise the next user on the same device inherits the prior identity.

app.js

// On logout
Sumidata.push('reset', [])

Track events

Fire any product event. Metadata keys with a leading underscore (_category, _feature, _surface) are extracted for AAARRR funnel tagging and do not show up in the stored payload. See Product events for the full taxonomy.

app.js

Sumidata.push('event', ['purchase', {
  orderId: 'ord_01HW…',
  totalAmount: 99.99,
  currency: 'USD'
}])

Register A/B experiments

Bind one or more variant assignments to the current session. Sticky: the first assignment per (session, experimentId) wins. See Experiments for the integration guide.

app.js

Sumidata.push('identifyExperiment', [[
  { id: 'pricing-v3', variant: 'control' }
]])

Read the session ID

Needed when you want to link a server-side conversion to the browser session, or register experiments from a backend feature-flag service. Returns null until the SDK finishes session creation.

app.js

const sessionId = window.Sumidata.getSessionId()

Exclude DOM elements

Add attributes to any element you want to keep out of replays.

index.html

<!-- skip this subtree entirely -->
<div data-sumidata-ignore>…</div>

<!-- mask value, keep structure -->
<input data-sumidata-mask />

04Troubleshooting

Common issues and how to fix them.

Sessions not appearing

Project ID mismatch — verify data-project-id against the Dashboard
Ad blocker stripping the script — test in a fresh browser profile
CSP blocking the SDK — see next section

Content Security Policy

Add the SDK domain to your CSP: script-src 'self' https://sdk.sumidata.io;