RealanalyticsDocs

Documentation

Configuration

Client options for createClient()

createClient

Collection is denied by default until you pass the visitor's consent decision. Calls made before analytics consent is granted are discarded. See Browser & Consent for setup.

import { createClient } from '@realanalytics/sdk'

const analytics = createClient({
  publicKey: 'pk_live_xxx',
  endpoint: 'https://realanalytics-ingest.ryanerkal1.workers.dev',
  autocapture: true,
  consent: {
    default: 'denied',
    respectGlobalPrivacyControl: true,
    respectDoNotTrack: true,
  },
  retry: {
    maxRetries: 3,
    baseDelay: 1000,
    maxDelay: 30000,
  },
  onError: (error, events) => {
    console.error(error.message, events.length)
  },
  onSuccess: (_events, receipt) => {
    console.log('newly accepted', receipt.accepted)
    console.log('duplicates in batch', receipt.duplicatesInBatch)
    console.log('duplicates already stored', receipt.duplicatesPreviouslyAccepted)
  },
})

Option reference

OptionTypeDefaultNotes
publicKeystringRequiredYour project public key
endpointstringhttps://realanalytics-ingest.ryanerkal1.workers.devCustom ingest URL
autocaptureboolean | AutocaptureOptionstrueEnable all or selected built-in tracking after analytics consent
consentConsentConfigDenied; privacy signals respectedInitial consent and privacy signal handling; see below
retryPartial<RetryConfig>3 / 1000 / 30000Retries 429/5xx/network failures
onError(error, events) => voidNoneCalled after final retry fails
onSuccess(events, receipt) => voidNoneReceipt separates newly accepted events, in-batch duplicates, and previously accepted duplicates

Consent options

  • consent.default?: ConsentInput defaults to 'denied'. A stored consent decision takes precedence. Use a real recorded decision if supplying an initial value.
  • consent.respectGlobalPrivacyControl?: boolean defaults to true. An active Global Privacy Control signal forces consent to remain denied.
  • consent.respectDoNotTrack?: boolean defaults to true. An active Do Not Track signal forces consent to remain denied.

Respected privacy signals take precedence over stored decisions and API calls. Pass consent manager changes to setConsent; never grant consent automatically. For example, call this handler when your consent manager supplies a decision:

import type { ConsentUpdate } from '@realanalytics/sdk'

function onConsentDecision(decision: ConsentUpdate) {
  analytics.setConsent(decision)
}

See the consent methods reference for input types and return values, and Browser & Consent for consent manager mapping.

Autocapture options

const analytics = createClient({
  publicKey: 'pk_live_xxx',
  autocapture: {
    pageviews: true,
    pageleave: true,
    clicks: true,
    scrollDepth: true,
    forms: true,
    errors: true,
    webVitals: true,
    outboundLinks: true,
    fileDownloads: true,
    rageClicks: true,
  },
})

Retry behavior

  • 429: uses Retry-After header when present
  • 5xx/network errors: exponential backoff with jitter
  • 4xx (except 429): no retry

Next Steps