Markers

For more information about Markers, visit the Markers Guide.

const gamebeastMarkers = gamebeast.markers;

Markers are batched and sent in the background. Each marker is validated when you send it: properties must be a plain JSON-serializable object, such as { level: 3 }, and are copied immediately, so changing the object afterwards doesn't affect the marker. An invalid marker is dropped with an error in the log rather than throwing, so one bad marker never fails a batch.

Failed sends are retried with exponential backoff. Rejections the backend won't accept on a retry (an invalid marker, a bad key) are logged and dropped.

You say who each marker is about. A marker without a distinctId is a server-level marker, attributed to this process's serverId. Pass serverId on a marker to attribute it to a different server unit, for example when one process serves many tenants.

Markers are sent in batches of 100, or every 5 seconds; change this with the markers option. During an outage the buffer holds up to 10,000 markers, then drops the oldest first. Call flush() or shutdown() before the process exits so nothing buffered is lost.

send(eventName, properties?, options?)Copy Anchor Link

→voidreturn type

Records a marker.

UsageCopy Anchor Link

gamebeastMarkers.send("purchase_completed", { sku: "gems_100" }, { distinctId: user.id });

// A server-level marker, not tied to a user
gamebeastMarkers.send("server_restarted");

// A multi-tenant process attributing a marker to the tenant's server unit
gamebeastMarkers.send("seat_added", {}, { distinctId: user.id, serverId: String(tenant.id) });

Deeplink attributionCopy Anchor Link

The browser SDK attributes a visitor's session to the Website deeplink or UTM campaign it landed from, and tags its markers with it. Markers your server sends aren't attributed unless you pass the attribution along.

Forward it from the page with your request (see Attributing server-side markers), then pass it as deeplink:

gamebeastMarkers.send(
  "purchase_completed",
  { sku: "gems_100" },
  { distinctId: user.id, deeplink: req.body.attribution }
);

Malformed attribution is dropped with a warning, and the marker is still sent. Gamebeast ignores a deeplink that doesn't exist or belongs to another project.

parseAttribution(url, referrer?)Copy Anchor Link

→DeeplinkAttribution | undefinedreturn type

Reads attribution from a landing URL, the same way the browser SDK does. Use it for pages your server renders without the browser SDK. Returns undefined when the URL has no utm_* parameters. Each call generates a new interactionId, so call it once per landing.

import { parseAttribution } from "@gamebeast/node";

const deeplink = parseAttribution(`https://example.com${req.url}`, req.headers.referer);
if (deeplink?.deeplinkData) {
  gamebeastMarkers.send(
    "$deeplink_landing",
    { landingUrl: deeplink.landingUrl },
    { distinctId: user.id, deeplink }
  );
}

Send $deeplink_landing once per landing: it's what the deeplink page counts. Send your other markers with the same deeplink for the rest of the session.

flush()Copy Anchor Link

→Promise<void>return type

Sends everything buffered now. Resolves once the requests have settled. In a serverless function, await it before the handler returns:

export async function handler(event) {
  gamebeast.markers.send(
    "checkout_completed",
    { total: event.total },
    { distinctId: event.userId }
  );
  await gamebeast.flush();
  return { statusCode: 200 };
}