Skip to main content

JavaScript Tracker

The DataBridge JavaScript tracker is a lightweight client library for sending events from browser and Node.js applications. It wraps the HTTP API with automatic batching and retry logic.

Coming Soon

The JavaScript tracker package (@databridge/browser) is under active development. In the meantime, you can use the HTTP API directly from JavaScript - see the example below.

Using the HTTP API Directly​

Until the SDK is published, you can send events using fetch:

Browser​

const API_SECRET = 'YOUR_SOURCE_API_SECRET';
const GATEWAY_URL = 'https://cloud.databridge.tech/capture';

async function trackEvent(schemaId, eventData) {
  const payload = {
    header: {
      client_timestamp_utc: Date.now(),
      client_tracker_name: 'my-website',
      client_tracker_version: '1.0.0'
    },
    events: [
      {
        $id: schemaId,
        $eid: crypto.randomUUID(),
        ...eventData
      }
    ]
  };

  await fetch(GATEWAY_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'api-secret': API_SECRET
    },
    body: JSON.stringify(payload)
  });
}

// Usage
trackEvent(
  'https://registry.databridge.tech/acme/purchase_completed/1-0-0',
  {
    order_id: 'ORD-12345',
    amount: 99.99,
    currency: 'USD'
  }
);

Node.js​

const API_SECRET = 'YOUR_SOURCE_API_SECRET';
const GATEWAY_URL = 'https://cloud.databridge.tech/track';

async function trackEvent(schemaId, eventData) {
  const { randomUUID } = await import('crypto');

  const payload = {
    header: {
      client_timestamp_utc: Date.now(),
      client_tracker_name: 'my-backend',
      client_tracker_version: '1.0.0'
    },
    events: [
      {
        $id: schemaId,
        $eid: randomUUID(),
        ...eventData
      }
    ]
  };

  const response = await fetch(GATEWAY_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'api-secret': API_SECRET
    },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    throw new Error(`Gateway returned ${response.status}`);
  }
}

Batching Multiple Events​

Send multiple events in a single request by adding them to the events array:

const payload = {
  header: {
    client_timestamp_utc: Date.now(),
    client_tracker_name: 'my-app',
    client_tracker_version: '1.0.0'
  },
  events: [
    {
      $id: 'https://registry.databridge.tech/acme/page_view/1-0-0',
      $eid: crypto.randomUUID(),
      url: '/products',
      referrer: 'https://google.com'
    },
    {
      $id: 'https://registry.databridge.tech/acme/button_clicked/1-0-0',
      $eid: crypto.randomUUID(),
      button_id: 'add-to-cart',
      page: '/products'
    }
  ]
};

Best Practices​

  1. Batch events - Collect events in memory and send them periodically (e.g., every 5 seconds or when the array reaches 10 events) to reduce HTTP overhead
  2. Generate UUIDs for $eid - Use crypto.randomUUID() in browsers or Node.js for reliable deduplication
  3. Handle errors gracefully - The gateway returns 200 on success with an empty body. Log non-200 responses but don't block the user experience
  4. Use navigator.sendBeacon - For page unload events in the browser, use sendBeacon to ensure delivery:
window.addEventListener('beforeunload', () => {
  const payload = JSON.stringify({
    header: {
      client_timestamp_utc: Date.now(),
      client_tracker_name: 'my-website',
      client_tracker_version: '1.0.0'
    },
    events: pendingEvents
  });

  navigator.sendBeacon(GATEWAY_URL, new Blob([payload], {
    type: 'application/json',
    headers: { 'api-secret': API_SECRET }
  }));
});

Next Steps​