Hyve SDK

The core SDK for integrating with the Hyve platform, providing authentication and telemetry capabilities for web applications and games.

Installation

npm install @hyve-sdk/js
# or
pnpm add @hyve-sdk/js
# or
yarn add @hyve-sdk/js

Quick Start

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

// Initialize the client
const client = new HyveClient({
  apiKey: 'your-api-key-here',
  isDev: true // Use dev environment (default)
});

// Authenticate from URL parameters
await client.authenticateFromUrl();

// Send telemetry event
await client.sendTelemetry(
  'app',        // event_location
  'user',       // event_category
  'login',      // event_action
  null,         // event_sub_category (optional)
  null,         // event_sub_action (optional)
  null,         // event_details (will be populated with additionalData JSON)
  {             // additionalData (optional) - JSON stringified into event_details
    timestamp: Date.now(),
    platform: 'web'
  }
);

Configuration

Client Configuration

const client = new HyveClient({
  apiKey: 'your-api-key',  // Required for telemetry
  isDev: true              // true = dev.hyve.gg, false = prod.hyve.gg
});

Environment Variables

Store your API key securely:

# .env
HYVE_API_KEY=your-api-key-here

const client = new HyveClient({
  apiKey: process.env.HYVE_API_KEY,
  isDev: process.env.NODE_ENV !== 'production'
});

Authentication

URL Parameter Authentication

The SDK supports two authentication formats via URL parameters:

Modern Token Format (Recommended)

https://yourapp.com?hyve-token=signature.address.randomBase64.timestamp

Legacy Format

https://yourapp.com?signature=0x...&message=encoded_message

Authenticating Users

// Authenticate from current URL
const isAuthenticated = await client.authenticateFromUrl();

if (isAuthenticated) {
  console.log('User ID:', client.getUserId());
  console.log('Session ID:', client.getSessionId());
}

// Or provide specific URL params
const params = new URLSearchParams(window.location.search);
const isAuthenticated = await client.authenticateFromUrl(params);

Checking Authentication Status

// Check if user is authenticated
if (client.isUserAuthenticated()) {
  const userId = client.getUserId(); // User's wallet address
  const sessionId = client.getSessionId(); // Unique session ID
}

Telemetry

Sending Telemetry Events

The sendTelemetry method provides full control over event tracking:

await client.sendTelemetry(
  eventLocation,      // Required: Where the event occurred
  eventCategory,      // Required: Main category
  eventAction,        // Required: Action taken
  eventSubCategory,   // Optional: Sub-category (pass null if not needed)
  eventSubAction,     // Optional: Sub-action (pass null if not needed)
  eventDetails,       // Optional: Human-readable description (pass null if not needed)
  additionalData      // Optional: Additional data object (pass null if not needed)
);

Telemetry Fields

All fields are always sent to the backend (with null for optional fields):

Field	Type	Description
session_id	string	Unique session identifier (auto-generated)
hyve_user_id	string	User's wallet address or 'anonymous'
event_location	string	Where the event occurred
event_category	string	Main category of event
event_action	string	Action taken
event_sub_category	string | null	Sub-category for granular classification
event_sub_action	string | null	Sub-action for detailed tracking
event_details	string | null	JSON stringified additional data or description

Examples

// Simple event
await client.sendTelemetry(
  'app', 'system', 'startup',
  null, null, null, null
);

// Event with all fields
await client.sendTelemetry(
  'game',                    // location
  'player',                  // category
  'achievement',             // action
  'combat',                  // sub-category
  'first_boss_defeat',       // sub-action
  null,                      // event_details will be JSON stringified additionalData
  {                          // additionalData - becomes JSON in event_details
    bossName: 'Dragon',
    playerLevel: 5,
    timeElapsed: 300,
    damageDealt: 1500,
    description: 'Player defeated the first boss'
  }
);

// User action tracking
await client.sendTelemetry(
  'app',
  'navigation',
  'click',
  'menu',
  'settings',
  null,      // event_details will be JSON stringified additionalData
  {          // additionalData - becomes JSON in event_details
    source: 'header',
    timestamp: Date.now(),
    description: 'User opened settings menu'
  }
);

// Error tracking
await client.sendTelemetry(
  'app',
  'error',
  'exception',
  'network',
  null,
  null,      // event_details will be JSON stringified additionalData
  {          // additionalData - becomes JSON in event_details
    errorCode: 'NETWORK_TIMEOUT',
    endpoint: '/api/profile',
    retryCount: 3,
    description: 'Failed to load user profile'
  }
);

API Reference

HyveClient

Constructor

new HyveClient(config?: TelemetryConfig)

Methods

Method	Returns	Description
authenticateFromUrl(urlParams?)	Promise<boolean>	Authenticate user from URL parameters
sendTelemetry(...)	Promise<boolean>	Send telemetry event
getUserId()	string | null	Get authenticated user's ID
getSessionId()	string	Get current session ID
isUserAuthenticated()	boolean	Check if user is authenticated
updateTelemetryConfig(config)	void	Update telemetry configuration
logout()	void	Clear user authentication
reset()	void	Reset client with new session

Types

interface TelemetryConfig {
  apiKey?: string;  // API key for telemetry service
  isDev?: boolean;  // Use dev environment (default: true)
}

interface TelemetryAdditionalData {
  [key: string]: any;  // Additional data object (JSON stringified into event_details)
}

Best Practices

1. API Key Management

// Use environment variables
const client = new HyveClient({
  apiKey: process.env.HYVE_API_KEY,
  isDev: process.env.NODE_ENV !== 'production'
});

2. Error Handling

try {
  const success = await client.sendTelemetry(...);
  if (!success) {
    console.warn('Telemetry failed to send');
    // Handle gracefully - don't break app flow
  }
} catch (error) {
  console.error('Telemetry error:', error);
  // Continue app execution
}

3. Anonymous Telemetry

// Telemetry works without authentication
// User ID will be 'anonymous'
const client = new HyveClient({ apiKey: 'key' });

// Still works - sends as anonymous user
await client.sendTelemetry('app', 'action', 'click', null, null, null, null);

4. Session Management

// Sessions persist until reset
const sessionId = client.getSessionId();

// Create new session if needed
client.reset(); // New session ID generated

Troubleshooting

API Key Not Working

1. Verify the API key is correct
2. Check you're using the right environment (dev vs prod)
3. Look for network errors in browser console
4. Ensure CORS is properly configured

Authentication Failing

1. Check URL parameter format
2. Verify signature is valid
3. Ensure timestamp is recent (within 5 minutes)
4. Check browser console for specific errors

Telemetry Not Sending

1. API key must be configured
2. Check network tab for 4xx/5xx responses
3. Verify required fields are provided
4. Look for console errors