Installation

npm

npm install @funtico/gameloop-sdk

yarn

yarn add @funtico/gameloop-sdk

pnpm

pnpm add @funtico/gameloop-sdk

CDN

For quick prototyping or simple integrations, you can use the CDN version:

<script src="https://funtico-frontend-js-sdk.pages.dev/funtico-sdk.min.js"></script>
<script>
  const sdk = new FunticoSDK({
    authClientId: 'your-client-id',
    env: 'sandbox' // or 'production'
  });
  // Use the SDK...
</script>

Quick Start

import { FunticoSDK } from '@funtico/gameloop-sdk';

// Initialize SDK for frontend use (no client secret needed)
const sdk = new FunticoSDK({
  authClientId: 'your-auth-client-id',
  env: 'sandbox' // or 'production'
});

// Start authentication flow - simple one-line call
await sdk.signInWithFuntico(
  window.location.origin + '/auth/callback'
);

// Get user info - tokens handled automatically
const userInfo = await sdk.getUserInfo();

// Submit game scores - authentication included
await sdk.saveScore(1500);

// Get leaderboard data - shows top players with their scores
const leaderboard = await sdk.getLeaderboard();

// Sign out - cleanup handled automatically
await sdk.signOut('/login');

Configuration

Basic Setup

import { FunticoSDK } from '@funtico/gameloop-sdk';

const sdk = new FunticoSDK({
  authClientId: 'your-auth-client-id', // Required
  env: 'sandbox' // Optional: 'sandbox' or 'production' (default: 'production')
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | authClientId | string | - | Your Funtico OAuth client ID (required) | | env | 'sandbox' \| 'production' | 'production' | Environment to use |

Environment Setup

• sandbox: For development and testing
• production: For live applications

📖 Step-by-Step Explanation

1. User Initiates Sign-In

// In your login button handler
const handleLogin = async () => {
  await sdk.signInWithFuntico(
    window.location.origin + '/auth/callback'
  );
  // User is now redirected to Funtico authentication and after he logs in he will be redirected to /auth/callback
};

2. User is authenticated

// Get current user information
const user = await sdk.getUserInfo();

// Submit game scores
await sdk.saveScore(1500);

// Get leaderboard data
const leaderboard = await sdk.getLeaderboard();
console.log('Top player:', leaderboard[0].user.username, 'with score:', leaderboard[0].score);

// Sign out when done (redirects to /login)
await sdk.signOut('/login');

Error Handling

The SDK uses a structured error system for reliable error handling:

import { SDKError, isSDKError } from '@funtico/gameloop-sdk';

try {
  const userInfo = await sdk.getUserInfo();
} catch (error) {
  if (isSDKError(error)) {
    console.error('SDK Error:', error.name, error.status);
    
    switch (error.name) {
      case 'auth_error':
        // User needs to re-authenticate
        console.log('Please log in again');
        await sdk.signInWithFuntico('/auth/callback');
        break;
        
      case 'internal_server_error':
        // Server or network issues
        console.error('Service temporarily unavailable');
        break;
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Error Types

| Error Type | Status Codes | Description | Recommended Action | |------------|--------------|-------------|-------------------| | auth_error | 401, 403 | Authentication required or expired | Redirect to login | | internal_server_error | 400, 500+ | Server or request errors | Show error message, retry |

Error Class

class SDKError {
  name: 'auth_error' | 'internal_server_error';
  status: number;
}

// Type guard function
function isSDKError(error: unknown): error is SDKError