SDK Documentation

Complete reference for the Dnomia Scout JavaScript SDK. Installation, configuration, methods, and troubleshooting.

INSTALLATION

Getting Started

Add the Dnomia SDK to your website by including the script tag in your HTML. The SDK loads asynchronously and won't block page rendering.

index.html

<!-- Add to your HTML <head> -->
<script>
(function() {
  window.dnomia = window.dnomia || [];
  dnomia.push(['init', {
    publicKey: 'pk_live_YOUR_KEY_HERE',
    consent: 'granted',
    debug: false
  }]);
  var s = document.createElement('script');
  s.async = true;
  s.src = 'https://cdn.dnomia.app/packages/sdk/latest/dnomia.min.js';
  document.head.appendChild(s);
})();
</script>

INITIALIZATION

Configuration

Initialize the SDK with your public key. The publicKey is required. All other options are optional.

Configuration

dnomia.push(['init', {
  publicKey: 'pk_live_XXX',  // Required
  consent: 'pending',        // 'pending' | 'granted' | 'denied'
  debug: false,              // Enable console logging
  respectDNT: true,          // Respect Do Not Track
  endpoint: 'https://scout.dnomia.app/v1/events'  // Custom endpoint
}]);

publicKeyYour store's public key (required)

consentInitial consent state: 'pending' (default), 'granted', or 'denied'

debugEnable console logging for debugging

respectDNTRespect Do Not Track browser setting (default: true)

endpointCustom endpoint URL (default: scout.dnomia.app)

METHODS

API Reference

track

Track a custom event with optional properties.

track(eventName, properties)

// Basic event
dnomia.push(['track', 'Button Clicked', {
  buttonId: 'cta-hero',
  page: '/pricing'
}]);

// E-commerce event
dnomia.push(['track', 'Placed Order', {
  orderId: 'ORD-12345',
  value: 299.90,
  currency: 'TRY',
  items: [
    {
      productId: 'SKU-001',
      name: 'Premium Plan',
      price: 299.90,
      quantity: 1
    }
  ]
}]);

identify

Associate the current anonymous user with a known identity.

identify(traits)

dnomia.push(['identify', {
  email: 'user@example.com',
  phone: '+905551234567',
  firstName: 'Ahmet',
  lastName: 'Yilmaz',
  plan: 'premium'  // Custom properties are supported
}]);

page

Manually track a page view. Called automatically on init.

page()

// Manual page view (auto-called on init)
dnomia.push(['page']);

// Page view is also tracked on SPA navigation
// if you call init with your router

consent

Update the consent state. Affects event queue behavior.

consent(state)

// Grant consent - flush queued events, start tracking
dnomia.push(['consent', 'granted']);

// Deny consent - stop tracking, clear queue
dnomia.push(['consent', 'denied']);

// Check current state via debug
dnomia.push(['debug', true]);

debug

Toggle debug mode for console output.

debug(enabled)

// Enable debug mode
dnomia.push(['debug', true]);

// Disable debug mode
dnomia.push(['debug', false]);

CONFIGURATION

Configuration Options

Automatic Events

Page views, sessions, and UTM parameters are captured automatically. No additional code required.

Event Batching

Events are batched (10 events or 3s timeout) before sending. Failed events persist to localStorage and retry on next session.

DNT Respect

respectDNT is enabled by default. When the browser's Do Not Track setting is on, the SDK enters silent mode.

Consent Default

Default consent is 'pending'. Events queue but don't send until consent is set to 'granted'.

EVENT SCHEMA

Event Format

Events sent to Dnomia follow this JSON structure:

Event JSON

{
  "event": "Placed Order",
  "properties": {
    "orderId": "ORD-12345",
    "value": 299.90,
    "currency": "TRY",
    "items": [...]
  },
  "context": {
    "page": {
      "url": "https://example.com/checkout",
      "title": "Checkout",
      "referrer": "https://example.com/cart"
    },
    "campaign": {
      "source": "google",
      "medium": "cpc",
      "name": "summer-sale"
    },
    "userAgent": "Mozilla/5.0...",
    "locale": "tr-TR",
    "timezone": "Europe/Istanbul"
  },
  "anonymousId": "uuid-v4",
  "userId": "user@example.com",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

TROUBLESHOOTING

Common Issues

Events are queued but not sent

Check that consent is set to 'granted'. Default consent is 'pending', which queues events without sending.

SDK not loading

Verify the script URL is correct and accessible. Check browser DevTools Network tab for errors.

Events being rejected

Verify your public key is correct. Check that your domain is registered in the Dnomia dashboard.