Skip to content

Analytics

The Analytics module allows you to measure game plays and track custom gameplay events.

Plays are counted for you — initializing the SDK records one, and there is nothing to call. Custom events are for everything else you want to measure: level completions, deaths, purchases, where players stop.

Where the numbers appear

Both show up on track.y8.com under your game, roughly two hours after the event — that is how long the aggregation runs behind.

Nothing confirms delivery at the time of the call, by design, so an event you just fired showing no trace is expected rather than a fault. Give it the two hours before concluding anything is wrong.

Track Custom Event

Track a simple event:

y8Sdk.trackCustomEvent("level_complete");

Track a number you want to read back out of your reports:

y8Sdk.trackCustomEvent("shipment_collected", 48135);

Track the same event happening several times at once:

y8Sdk.trackCustomEvent("enemy_defeated", null, 3);

Parameters

Parameter Required Description
name Yes Event name used to group events in reports. Keep names stable.
value No What you measured — a score, a level, a coin total, a duration. Gets its own distribution report.
amount No How many times the event happened. Creates one identical entry per occurrence. Default: 1. Maximum: 100.

Value or Amount?

value is what you measured. amount is how many times it happened.

Swapping the two is the easiest mistake to make with this method, and nothing about it is loud — the events keep arriving and the reports keep drawing.

y8Sdk.trackCustomEvent("shipment_collected", 48135);

creates one entry carrying the number 48,135, and that number is what the event's distribution report is built from.

y8Sdk.trackCustomEvent("shipment_collected", null, 48135);

creates 48,135 identical entries, each one recording nothing more than that a shipment was collected. The number itself is stored nowhere — you get a count, not a measurement.

amount repeats the event, it does not record a number

// WRONG — creates 48,135 identical entries and records no number
y8Sdk.trackCustomEvent("shipment_collected", null, 48135);

// RIGHT — creates one entry recording the number 48,135
y8Sdk.trackCustomEvent("shipment_collected", 48135);

If the number can climb past a hundred — a score, a coin total, a distance, a duration in milliseconds — it is a value.

Using Amount

amount has one purpose: replacing a loop that would send the same event several times in a row.

// The player cleared three enemies at once.
// Creates 3 entries of "enemy_defeated" in a single request.
y8Sdk.trackCustomEvent("enemy_defeated", null, 3);

Instead of:

for (let i = 0; i < 3; i++) {
    y8Sdk.trackCustomEvent("enemy_defeated");
}

Both create three entries; the first sends one request instead of three.

amount is capped at 100. A larger amount is recorded as a single occurrence and warns in the browser console, because a number that big is almost always a measurement that belongs in value.

Event Naming

Keep event names stable and put changing information in value.

Prefer:

y8Sdk.trackCustomEvent("track_win", 3);

instead of:

y8Sdk.trackCustomEvent("track_win_3");

This keeps your reports easier to analyze.

Important Notes

  • trackCustomEvent() returns nothing.
  • It does not return a Promise.
  • Do not use await.
  • The method does not throw errors.
  • Analytics should not block the game loop.
  • Avoid sending events every frame or game tick.
  • amount is capped at 100; a larger amount is recorded as a single occurrence.
  • Events are not sent when game statistics are disabled in the developer settings.

Analytics play tracking is available automatically when the SDK is initialized.

Note

Custom event tracking is not currently available in the Unity SDK.

Analytics play tracking is available automatically when the SDK is initialized.

Note

Custom event tracking is not currently available in the Construct 3 integration.

Analytics play tracking is available automatically when the SDK is initialized.

Note

Custom event tracking is not currently available in the Haxe SDK.