API Destination

Web Source code Package

The API destination allows you to send events to any HTTP endpoint with customizable data transformation and transport methods.

Installation

npm install @walkeros/web-destination-api

Setup

import { createCollector } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { collector, elb } = await createCollector({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
        },
      },
    },
  },
});

Configuration reference

Property	Type	Description	More
url*	string	The HTTP endpoint URL to send events to
headers	Record<string, string>	Additional HTTP headers to include with requests
method	string	HTTP method for the request
transform	function	Function to transform event data before sending
transport	'fetch' | 'xhr' | 'beacon'	Transport method for sending requests

* Required fields

Usage

Basic Usage

import { createCollector } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { collector, elb } = await createCollector({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            Authorization: 'Bearer your-token',
          },
        },
      },
    },
  },
});

Advanced Usage with Transform

import { createCollector } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { collector, elb } = await createCollector({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
          transport: 'fetch',
          transform: (event, config, mapping) => {
            // Custom transformation logic
            return JSON.stringify({
              timestamp: Date.now(),
              event_name: `${event.entity}_${event.action}`,
              properties: event.data,
              context: event.context,
            });
          },
        },
      },
    },
  },
});

Examples

Sending to Analytics API

import { createCollector } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { collector, elb } = await createCollector({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://analytics.example.com/track',
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'your-api-key',
          },
          transform: (event) => {
            return JSON.stringify({
              event_type: `${event.entity}_${event.action}`,
              user_id: event.user?.id,
              session_id: event.user?.session,
              properties: event.data,
              timestamp: event.timing,
            });
          },
        },
      },
    },
  },
});

Using Beacon Transport

For critical events that need to be sent even when the page is unloading:

// Add to existing createCollector config
const { collector, elb } = await createCollector({
  destinations: {
    criticalApi: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/critical-events',
          transport: 'beacon', // Reliable for page unload scenarios
        },
      },
    },
  },
});

Custom Data Mapping

Use mapping rules to control which events are sent:

// Add to existing createCollector config
const { collector, elb } = await createCollector({
  destinations: {
    api: {
      code: destinationAPI,
      config: {
        settings: {
          url: 'https://api.example.com/events',
        },
        mapping: {
          entity: {
            action: {
              data: 'data',
            },
          },
        },
      },
    },
  },
});

Transport Methods

• fetch (default): Modern, promise-based HTTP requests
• xhr: Traditional XMLHttpRequest for older browser compatibility
• beacon: Uses Navigator.sendBeacon() for reliable data transmission during page unload

Mapping

By default the sendWeb function is used to send the events to an API.

Event

{
  name: "entity action",
  data: {
    string: "foo",
    number: 1,
    boolean: true,
    array: [
      0,
      "text",
      false
    ]
  },
  context: {
    dev: [
      "test",
      1
    ]
  },
  globals: {
    lang: "elb"
  },
  custom: {
    completely: "random"
  },
  user: {
    id: "us3r",
    device: "c00k13",
    session: "s3ss10n"
  },
  nested: [
    {
      entity: "child",
      data: {
        is: "subordinated"
      },
      nested: [],
      context: {
        element: [
          "child",
          0
        ]
      }
    }
  ],
  consent: {
    functional: true
  },
  id: "1760055217000-gr0up-1",
  trigger: "test",
  entity: "entity",
  action: "action",
  timestamp: 1760055217000,
  timing: 3.14,
  group: "gr0up",
  count: 1,
  version: {
    source: "0.1.2",
    tagging: 1
  },
  source: {
    type: "web",
    id: "https://localhost:80",
    previous_id: "http://remotehost:9001"
  }
}

{ name: "entity action", data: { string: "foo", number: 1, boolean: true, array: [ 0, "text", false ] }, context: { dev: [ "test", 1 ] }, globals: { lang: "elb" }, custom: { completely: "random" }, user: { id: "us3r", device: "c00k13", session: "s3ss10n" }, nested: [ { entity: "child", data: { is: "subordinated" }, nested: [], context: { element: [ "child", 0 ] } } ], consent: { functional: true }, id: "1760055217000-gr0up-1", trigger: "test", entity: "entity", action: "action", timestamp: 1760055217000, timing: 3.14, group: "gr0up", count: 1, version: { source: "0.1.2", tagging: 1 }, source: { type: "web", id: "https://localhost:80", previous_id: "http://remotehost:9001" } }

Mapping

{
  data: "data"
}

{ data: "data" }

Result

No event yet.

No event yet.