SDK reference

Every public call of the web SDK 0.4.0 (the global datacub from the script tag, typed by datacub.d.ts) and of @datacub/react-native 0.1.0. No call ever throws; a refused call does nothing.

Web SDK

import type { InitOptions, Properties } from './datacub'

const options: InitOptions = { apiHost: 'https://ingest.datacub.example', hashRouting: false, autocapture: true, release: '1.4.0' }
datacub.init('pk_live_YOUR_PROJECT_KEY', options)

const props: Properties = { plan: 'pro', seats: 3 }
datacub.track('plan_changed', props)
datacub.identify('user_8f3a2c', { account: 'ws_51', email: 'sara@example.sa', name: 'Sara', phone: '+966551234567' })
datacub.reset()
datacub.consent.revoke()
CallDoes
datacub.init(publicKey, options?)starts the SDK once; later calls are ignored. Calls before it wait (up to 100)
datacub.track(event, properties?)a custom event. Rules
datacub.identify(userId, { account?, email?, name?, phone?, ...traits })after login: links this browser's activity to the user; traits describe them. More
datacub.reset()at logout: new Guest ID and session
datacub.consent.grant(options?)for consent first: starts storing and sending. Options: method, policyVersion, overrideGPC. Also clears a stored opt-out
datacub.consent.revoke()works in every project: stops, deletes the SDK's other cookies and the queue, and remembers the opt-out on this browser

init options: apiHost (default https://ingest.datacub.example), hashRouting (default false), autocapture (default true), release, requireConsent (default false: see asking for consent). Details.

HTML attributes: data-datacub-name="..." names a click or form; class="datacub-no-capture" or data-datacub-no-capture excludes an element and everything inside it. Script tag attributes: data-key, data-api-host, data-require-consent.

Cookies, all first party: datacub_id (Guest ID, 400 days), datacub_u (user ID), datacub_a (account ID), datacub_ss (session, 30 minutes). Each name ends with _ and the first eight characters after pk_live_ or pk_test_ in your key (datacub_id_k7Qm2xPa): every subdomain running the same key shares one visitor and session, and a second key on the same site gets its own. With requireConsent they are written only after grant(). After revoke() the only cookie is datacub_optout (400 days, no identifier).

Feedback widget

The questions you write in the dashboard's Feedback page show through a separate file, loaded only on sites that use it. Add it next to the SDK:

<script src="https://ingest.datacub.example/v1/feedback.js" async></script>
Call or attributeDoes
datacub.ask(questionId, { into? })shows a question whose trigger is "from my code"; into places it inline in an element or selector
<div data-datacub-ask="questionId"></div>the same, inline, without code
datacub.feedback(), or any element with data-datacub-feedbackopens the general "Send feedback" card

Both calls exist only once the widget has loaded.

@datacub/react-native

import datacub, { type InitOptions, VERSION } from '@datacub/react-native'
import { trackNavigation } from '@datacub/react-native/navigation'

const options: InitOptions = {
  apiHost: 'https://ingest.datacub.example',
  storage: { getItem: () => null, setItem: () => {}, removeItem: () => {} },
  app: { applicationId: 'sa.example.shop', nativeApplicationVersion: '2.3.0', nativeBuildVersion: '87' },
}
datacub.init('pk_live_YOUR_PROJECT_KEY', options)

datacub.track('order_placed', { items: 2 })
datacub.screen('Checkout', { step: 'payment' })
datacub.identify('user_8f3a2c', { account: 'ws_51' })
datacub.reset()
datacub.consent.revoke()
await datacub.flush()
console.log(VERSION, typeof trackNavigation)
CallDoes
datacub.init(publicKey, options?)starts the SDK once. Options: storage, app, apiHost, requireConsent
datacub.track(event, properties?)a custom event
datacub.screen(name, properties?)a screen view; the same name twice in a row counts once
datacub.identify(userId, { account?, email?, name?, phone?, ...traits })after login, as on the web
datacub.reset()at logout
datacub.flush()sends what is queued; resolves when done or failed, never rejects
datacub.consent.grant(options?), datacub.consent.revoke()as on the web; grant takes method and policyVersion. The opt-out is a flag in the SDK's stored value
trackNavigation(ref) from @datacub/react-native/navigationscreen views from a React Navigation container ref; returns an unsubscribe function

Events datacub sends for you

EventSDKWhen
$pageview, $pageleavewebpage views
$click, $form_submitwebclicks and submits
$screenmobiledatacub.screen or trackNavigation
$consentbothdatacub.consent.grant(), when the project asks for consent first
$identifybothdatacub.identify with a new user, with any traits
$setbothdatacub.identify with traits for the user already identified

Event names starting with $ are reserved for these.

HTTP

Both SDKs send POST {apiHost}/v1/batch with a JSON body of up to 100 events. You do not need to call it yourself. If you proxy it, pass the body through unchanged and keep the response status, including Retry-After.