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()| Call | Does |
|---|---|
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 attribute | Does |
|---|---|
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-feedback | opens 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)| Call | Does |
|---|---|
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/navigation | screen views from a React Navigation container ref; returns an unsubscribe function |
Events datacub sends for you
| Event | SDK | When |
|---|---|---|
$pageview, $pageleave | web | page views |
$click, $form_submit | web | clicks and submits |
$screen | mobile | datacub.screen or trackNavigation |
$consent | both | datacub.consent.grant(), when the project asks for consent first |
$identify | both | datacub.identify with a new user, with any traits |
$set | both | datacub.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.