JavaScript SDK

The JavaScript SDK runs in browsers and Node.js. It validates, transforms, samples, routes, and handles events from a generated datafile.

Installation#

npm install @eventvisor/sdk

Creating an instance#

import { createEventvisor } from "@eventvisor/sdk";
const datafile = await fetch("https://cdn.example.com/eventvisor-web.json")
  .then((response) => response.json());
const eventvisor = createEventvisor({
  datafile,
  initialAttributes: {
    deviceId: "device-123",
  },
});
await eventvisor.onReady();

createEventvisor() is the runtime factory. Use the exported Eventvisor type when an instance must be passed through your application.

Events#

const tracked = await eventvisor.track("pageView", {
  url: "https://example.com/home",
});

The promise resolves to the final transformed event, or null when the event is rejected.

Public SDK operations are processed in call order. This prevents a setAttribute() followed immediately by track() from racing, even when the application keeps both promises and awaits them together.

Destination transports run in parallel. The promise waits for all selected attempts, but transport modules define whether an attempt is immediate delivery or queue acceptance. See the event pipeline.

Attributes#

await eventvisor.setAttribute("userId", "user-123");
eventvisor.getAttributeValue("userId");
eventvisor.getAttributes();
eventvisor.isAttributeSet("userId");
await eventvisor.removeAttribute("userId");

Modules#

Modules provide transports, handlers, lookups, and storage.

import { createConsoleModule } from "@eventvisor/module-console";
const eventvisor = createEventvisor({
  datafile,
  modules: [createConsoleModule()],
});
const removeModule = eventvisor.addModule({
  name: "custom",
  setup(api) {
    api.reportDiagnostic({
      level: "info",
      code: "custom_ready",
      message: "Custom module is ready",
      details: {},
    });
  },
  async close() {
    // Release subscriptions and resources.
  },
});
await removeModule?.();

Modules can also be removed by name with await eventvisor.removeModule("custom").

Duplicate module names are rejected and reported as diagnostics.

Diagnostics#

Use diagnostics for structured SDK and module reports.

const eventvisor = createEventvisor({
  datafile,
  logLevel: "warn",
  onDiagnostic(diagnostic) {
    sendToObservabilityPlatform(diagnostic);
  },
});
const unsubscribe = eventvisor.onDiagnostic((diagnostic) => {
  console.log(diagnostic.level, diagnostic.code, diagnostic.message);
});
unsubscribe();

Diagnostics contain level, code, message, details, and optional module or error information. Error diagnostics also trigger the SDK error event. See Diagnostics for stable code families and monitoring guidance.

Updating a datafile#

Datafiles merge by default. This is useful when an application loads more than one target or product area.

await eventvisor.setDatafile(additionalDatafile);

Pass true to replace the current datafile completely:

await eventvisor.setDatafile(nextDatafile, true);

Invalid JSON is reported with the message Could not parse datafile and does not replace the active datafile.

Events from the SDK#

const unsubscribe = eventvisor.on("datafile_set", ({ replaced }) => {
  console.log({ replaced });
});

Available events are ready, datafile_set, attribute_set, attribute_removed, event_tracked, and error.

Child instances#

spawn() creates an independent instance using the current datafile. Pass child-specific modules, diagnostics, and attributes as needed.

const child = eventvisor.spawn({
  initialAttributes: { application: "checkout" },
});

Closing#

await eventvisor.flush();
await child.close();
await eventvisor.close();

flush() asks all modules to attempt queued work. Closing flushes modules, then releases module resources, diagnostic subscriptions, and SDK event listeners.

Datafile metadata#

eventvisor.getRevision();
eventvisor.getSchemaVersion();