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>

Using a bundler (Vite, Vike, React, Next.js)? Install the package and call init() client-side instead — same SDK, no external script, CSP-friendly:

terminal

npm i @sumidata/browser

main.ts

import Sumidata from '@sumidata/browser'

Sumidata.init({ projectId: 'YOUR_PROJECT_ID' })

With the package, the runtime methods are typed instance calls — Sumidata.event(…), Sumidata.identify(…) — identical in effect to the push() form below. See the install guide for per-framework snippets.

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-masking

Privacy masking level for session replays. Three levels:

fieldsOnly (default) — every form input value is recorded as asterisks.
fieldsAndLabels — input values plus <label> text are masked. Placeholder and aria-label attributes are not masked.
dangerouslyNoMask — raw input values are recorded.

Password fields are always masked, at every level. Omitting the attribute means fieldsOnly; any other value logs a console warning and falls back to fieldsOnly.

data-masking="fieldsAndLabels"

data-autocapture

Automatic event collection — pageviews, clicks, form submits, and scroll depth arrive in the dashboard without a single line of tracking code. Two values:

on (default) — the SDK sends $pageview (including SPA navigations), $autocapture_click, $autocapture_submit, and $autocapture_scroll depth milestones alongside your manual events.
off — disables all automatic collection, including scroll depth. Manual push('event', …) calls are unaffected.

Form field values are never collected by autocapture, in any data-masking mode. See Automatic events for the full event reference and the masking interaction.

data-autocapture="off"

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. (Conversions use the ingest API — see Conversions.)
`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', ['add_to_cart', {
  productId: 'plan_pro_monthly',
  _category: 'activation',
  _feature: 'cart'
}])

push('event', …) is for product events only. Revenue conversions (orderId + totalAmount) are not sent this way — every property except _category / _feature / _surface is stored in payload, so the conversion fields would never reach the conversion columns. Send them to the ingest API instead — see Conversions.

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()

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;