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.

Event	location	category	action	details
Session start	game	session	start	—
Session end	game	session	end	—
Lobby loading start	game	loading	start	—
Lobby loading end	game	loading	end	—
Game loading start	game	game_loading	start	—
Game loading end	game	game_loading	end	—
Lobby init	game	lobby	init	—
Gameplay start	game	gameplay	start	—
Gameplay end	game	gameplay	end	—
Store open	game	store	start	—
Purchase complete	game	purchase	complete	{ item_name }
Purchase fail	game	purchase	fail	{ item_name }
Purchase cancel	game	purchase	cancel	{ item_name }

// 1. On game init
await hyve.sendTelemetry('game', 'session', 'start');
await hyve.sendTelemetry('game', 'loading', 'start');

// 2. After assets load
await hyve.sendTelemetry('game', 'loading', 'end');
await hyve.sendTelemetry('game', 'lobby', 'init');

// 3. When gameplay begins
await hyve.sendTelemetry('game', 'gameplay', 'start');

// 4. When gameplay ends
await hyve.sendTelemetry('game', 'gameplay', 'end');

// 5. On unload
await hyve.sendTelemetry('game', 'session', 'end');

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));