Deeplink attribution

For more information about website deeplinks, visit the Deeplinks Guide.

When GamebeastClient starts on a page, it reads the page URL for UTM parameters. A Gamebeast Website deeplink sends visitors to your URL tagged with your UTM values and utm_id=gb_<link ID>, for example:

https://example.com/pricing?utm_source=twitter&utm_medium=deeplink&utm_campaign=launch&utm_id=gb_summer-mfz3k0q7

From that URL the SDK:

1. Saves the attribution with the current session. The first attribution in a session wins: a second deeplink in the same session is ignored. Sessions are shared across tabs and end after sessionTimeoutMinutes (default 30) without activity, and the attribution ends with them.
2. Sends one $deeplink_landing marker, if the URL carried a Gamebeast deeplink (utm_id starting with gb_). Its properties are referrer (document.referrer, when there is one) and landingUrl (the URL without its utm_* parameters). The deeplink page counts these as landings.
3. Attaches the deeplink and the UTM values to every marker for the rest of the session, alongside the marker's properties (never inside them, so your own property names can't collide). That's what makes the visitor's markers match the deeplink's filters and breakdowns in the Query Builder.

A URL with UTM parameters but no gb_ id is attributed to its UTM values the same way, without a landing marker. A visit with no utm_* parameters changes nothing.

In the dashboard, the UTM values show up on each attributed marker as properties named $utm_source, $utm_medium, $utm_campaign, $utm_content, $utm_term, and $utm_id, which you can filter and break down by in the Query Builder. The $utm_ prefix is reserved: if your own marker properties use it, Gamebeast drops those keys. The $utm_* properties count toward the marker's property limit.

Gamebeast checks each deeplink when markers arrive. An unknown link, or one that belongs to another project, is ignored: the markers are kept without the attribution.

Nothing happens during server-side rendering: an inert client never reads the URL.

OptionsCopy Anchor Link

attributionCopy Anchor Link

→DeeplinkAttribution | undefinedreturn type

How the current session was acquired, or undefined when it wasn't through a deeplink or UTM link. Returns a copy.

interface DeeplinkAttribution {
  // Present when the landing URL carried a Gamebeast deeplink (utm_id=gb_<link ID>).
  // interactionId is generated for each landing.
  deeplinkData?: { slug: string; interactionId: string };

  // The landing URL's UTM parameters, without the utm_ prefix.
  utm?: {
    source?: string;
    medium?: string;
    campaign?: string;
    content?: string;
    term?: string;
    id?: string;
  };

  // document.referrer at landing, when there was one.
  referrer?: string;

  // The landing URL without its utm_* parameters.
  landingUrl?: string;

  // When the landing was recorded, in epoch milliseconds.
  capturedAt: number;
}

UsageCopy Anchor Link

const source = gamebeast.attribution?.utm?.source ?? "direct";

captureAttribution(url)Copy Anchor Link

→voidreturn type

Reads attribution from url. The SDK does this for the page URL when it starts. Call it yourself when that isn't the URL the visitor landed on, for example a single-page app whose router rewrites the address before the SDK is created, or with captureAttribution: false. If the session already has attribution, this does nothing.

UsageCopy Anchor Link

// Save the landing URL before the router changes it
const landingUrl = window.location.href;

// ...later, once the app creates the SDK
const gamebeast = new GamebeastClient({ apiKey: "abcd-efgh-1234-5678", captureAttribution: false });
gamebeast.captureAttribution(landingUrl);

Attributing server-side markersCopy Anchor Link

Markers your server sends with the Node.js SDK aren't attributed automatically, because the server doesn't see the landing URL. Send the browser's attribution with your request and pass it on:

await fetch("/api/checkout", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ cart, attribution: gamebeast.attribution }),
});

gamebeast.markers.send(
  "purchase_completed",
  { total: cart.total },
  { distinctId: user.id, deeplink: req.body.attribution }
);