Telemetry

Send analytics events to the Hyve platform. Requires both hyve-access JWT and game-id URL params.

sendTelemetry

await hyve.sendTelemetry(
  location,      // string — where the event occurred (required)
  category,      // string — main category (required)
  action,        // string — action taken (required)
  subCategory?,  // string | null
  subAction?,    // string | null
  details?,      // Record<string, unknown> | string | null
  platformId?    // string | null
): Promise<boolean>  // false if JWT/game-id missing or details invalid

import { useHyveSdk } from '@hyve-sdk/js/react';

function Game() {
  const hyve = useHyveSdk();

  const handleLevelComplete = async () => {
    await hyve.sendTelemetry('game', 'level', 'complete', null, null, { score: 1500 });
  };
}

Required Lifecycle Events

Every game must implement these events. The platform uses them for analytics and session tracking.

The SDK ships a predefined helper for each — prefer these over raw sendTelemetry() calls so the event taxonomy stays consistent.

Event	SDK helper	Emits (location / category / action)	details
Session start	hyve.sessionStart()	game / session / start	—
Session end	hyve.sessionEnd()	game / session / end	—
Lobby loading start	hyve.lobbyLoadingStart()	game / loading / start	—
Lobby loading end	hyve.lobbyLoadingEnd()	game / loading / end	—
Game loading start	hyve.gameLoadingStart()	game / game_loading / start	—
Game loading end	hyve.gameLoadingEnd()	game / game_loading / end	—
Lobby init	hyve.lobbyInit()	game / lobby / init	—
Gameplay start	hyve.gameplayStart()	game / gameplay / start	—
Gameplay end	hyve.gameplayEnd()	game / gameplay / end	—
Store open	hyve.storeOpen()	game / store / start	—
Purchase complete	hyve.purchaseComplete(itemName)	game / purchase / complete	{ item_name }
Purchase fail	hyve.purchaseFail(itemName)	game / purchase / fail	{ item_name }
Purchase cancel	hyve.purchaseCancel(itemName)	game / purchase / cancel	{ item_name }

Each helper returns Promise<boolean> (matching sendTelemetry) — false if JWT/game-id is missing.

hyve.gameplayStart() and hyve.gameplayEnd() also notify the CrazyGames SDK when running on that platform, so a single call covers both the required telemetry event and the platform hook.

// 1. On game init
await hyve.sessionStart();
await hyve.lobbyLoadingStart();

// 2. After assets load
await hyve.lobbyLoadingEnd();
await hyve.lobbyInit();

// 3. When gameplay begins
await hyve.gameplayStart();

// 4. When gameplay ends
await hyve.gameplayEnd();

// 5. On unload
await hyve.sessionEnd();

// Purchases
await hyve.purchaseComplete('coin_pack_small');
await hyve.purchaseFail('coin_pack_small');
await hyve.purchaseCancel('coin_pack_small');

eventDetails Validation

The SDK validates details before sending. Invalid values return false without throwing.

// Valid
{ score: 100, level: 5 }
'{"score":100}'

// Invalid (returns false): circular references, functions, undefined values

Sanitize before sending if data may contain undefined:

const clean = JSON.parse(JSON.stringify(data, (_, v) => v === undefined ? null : v));