Analytics

The retipie.analytics namespace reports what's happening inside your game. Every call is fire-and-forget: it returns nothing and waits for no acknowledgement. A call with an invalid name or number is ignored. Pass plain JSON-serializable values; a circular object or a BigInt in event data throws.

Reports travel to the app over a size- and rate-limited channel. A game may send at most 60 SDK messages per second in total, and about 128 KB of message text per second. Anything over that is dropped, so report at meaningful moments rather than every frame.

analytics.loadingProgress(percent)

Report asset loading progress as a number from 0 to 100. Values outside the range are clamped, and values that aren't finite numbers are ignored.

preloadAssets((loaded, total) => {
  retipie.analytics.loadingProgress((loaded / total) * 100);
});

The loading indicator shows the progress you report while the game loads. Reporting is optional: a game that never reports is treated as ready once its page has loaded. But if you do report progress while the game is loading, always finish with 100. A game that reports progress and never reaches 100 stays on the loading screen until the load times out (30 seconds) and fails.

analytics.gameplayStart() / analytics.gameplayStop()

Mark the beginning and end of active gameplay.

function startRun() {
  retipie.analytics.gameplayStart();
  // … game loop runs …
}

function endRun() {
  retipie.analytics.gameplayStop();
  retipie.leaderboards.submitScore(finalScore);
}

Until you call gameplayStop(), the platform assumes the game is being played, so you don't have to call gameplayStart() for the first run. After gameplayStop(), the game counts as not in active play — a menu or game-over screen — until your next gameplayStart(). Call gameplayStop() when a run really ends so idle screens aren't counted as play time.

analytics.gameplayRestart()

Call once when the player voluntarily chooses to try the game again after a run. The platform records this separately from first play, a short exit, and a technical retry. This marker does not start the active-play timer; call gameplayStart() when the next run actually begins.

function onTryAgainClick() {
  retipie.analytics.gameplayRestart();
  resetRun();
  retipie.analytics.gameplayStart();
}

Do not emit it on first play, an automatic round transition, a WebView reload, or recovery from a loading error or crash. A player resuming a paused run is not starting another attempt.

Godot exposes RetiPie.analytics.gameplay_restart(); Unity exposes RetiPieAnalytics.GameplayRestart().

analytics.trackEvent(name, data?)

trackEvent(
  name: string,
  data?: Record<string, string | number | boolean | null>,
): void

Record a creator-defined event, for example a level or feature milestone.

retipie.analytics.trackEvent('level_complete', { level: 4, hintsUsed: 2 });

Limits. The platform drops an event that breaks any of these limits, without an error:

• name is required: a non-empty string of at most 128 characters. An empty or non-string name is ignored by the SDK itself.
• The whole message, name and data together, is at most 16,384 characters.
• data is optional and must be a flat object with at most 32 keys. Keys are at most 128 characters.
• Values must be a string (at most 1,024 characters), a finite number, a boolean, or null. Nested objects and arrays are not supported, and one invalid value drops the whole event.

Return value. None. trackEvent returns undefined immediately and there is no way to learn whether the event was recorded.

Unity's RetiPieAnalytics.TrackEvent(name, Dictionary<string, object>) and Godot's RetiPie.analytics.track_event(name, data) follow the same limits. Unity converts values that aren't strings, booleans, or int, long, float and double numbers into strings.