⚠️ Developer Preview

The Gx402 SDK is still in active development.
Some features may not function as expected, and APIs are subject to change.
For production use, please wait for the stable release.

Basic Integration Tutorial

This tutorial will guide you through integrating the Gx402 SDK into an existing game project, covering the essential steps to get x402 functionality working.

Overview

By the end of this tutorial, you will have:

Integrated the Gx402 SDK into your game
Set up basic x402 processing
Implemented simple data synchronization
Added user authentication

Prerequisites

An existing game project (Unity, Unreal, WebGL, or other supported platform)
A Gx402 API key from your dashboard
Basic knowledge of your game’s architecture

Step 1: Install the SDK

For WebGL/JavaScript Projects

If you’re using NPM:

npm install @Gx402/web-sdk

If you prefer CDN, add to your HTML:

<script src="https://unpkg.com/@Gx402/web-sdk/dist/Gx402.min.js"></script>

For Unity Projects

Open your Unity project
Go to Window > Package Manager
Click the + button and select “Add package from git URL”
Enter: https://github.com/Gx402/unity-sdk.git

For Unreal Engine Projects

Download the plugin from Releases
Create a Plugins folder in your project if it doesn’t exist
Extract the plugin to YourProject/Plugins/Gx402-sdk
Restart Unreal Editor and enable the plugin

Step 2: Initialize the SDK

WebGL/JavaScript

import { Gx402SDK } from '@Gx402/web-sdk';

// Initialize early in your game startup
const Gx402 = new Gx402SDK({
  apiKey: 'YOUR_API_KEY_HERE',
  environment: 'development', // Change to 'production' for live builds
  enableRealtimeSync: true,
  debug: true // Set to false in production
});

// Wait for initialization
await Gx402.init();
console.log('Gx402 SDK initialized successfully');

Unity (C#)

using Gx402;
using UnityEngine;

public class Gx402Manager : MonoBehaviour
{
    void Start()
    {
        // Initialize the SDK
        Gx402Manager.Initialize("YOUR_API_KEY_HERE");
        
        // Configure options
        Gx402Manager.Configure(new Gx402Config
        {
            EnableRealtimeSync = true,
            LogLevel = Gx402LogLevel.Debug
        });
        
        Debug.Log("Gx402 SDK initialized successfully");
    }
}

Unreal Engine (C++)

#include "Gx402SDK.h"

void AMyGameMode::StartPlay()
{
    Super::StartPlay();
    
    // Configure the SDK
    FGx402Config Config;
    Config.ApiKey = TEXT("YOUR_API_KEY_HERE");
    Config.bEnableRealtimeSync = true;
    Config.LogLevel = EGx402LogLevel::Debug;
    
    // Initialize the SDK
    UGx402Manager::Initialize(Config);
    
    UE_LOG(LogTemp, Log, TEXT("Gx402 SDK initialized successfully"));
}

Step 3: Add User Authentication

Authentication is crucial for personalized x402 experiences.

WebGL/JavaScript

// Authenticate the user when they start playing
async function authenticateUser(userId, authData) {
  try {
    await Gx402.authenticate(userId, authData);
    console.log('User authenticated successfully');
    
    // Now you can use user-specific x402 features
    return true;
  } catch (error) {
    console.error('Authentication failed:', error);
    return false;
  }
}

// Example usage
const isAuthenticated = await authenticateUser('user-123', 'auth-token');

Unity (C#)

async void AuthenticateUser(string userId, string token)
{
    Gx402Manager.Authenticate(userId, token, (success, result) => {
        if (success) {
            Debug.Log($"User {userId} authenticated successfully");
            OnUserAuthenticated();
        } else {
            Debug.LogError($"Authentication failed: {result.ErrorMessage}");
        }
    });
}

void OnUserAuthenticated()
{
    // Enable x402 features that require authentication
    EnableAdvancedFeatures();
}

Step 4: Implement x402 Data Processing

Now let’s add x402 processing to your game data.

WebGL/JavaScript

// Process game data with x402 functionality
async function processGameData(gameEvent) {
  try {
    const x402Result = await Gx402.processX402Data({
      event: gameEvent.type,
      data: gameEvent.payload,
      timestamp: Date.now(),
      playerId: getCurrentPlayerId()
    });
    
    // Apply x402 enhancements to your game
    return applyX402Enhancements(gameEvent, x402Result);
  } catch (error) {
    console.error('x402 processing failed:', error);
    // Fallback to normal game processing
    return gameEvent.payload;
  }
}

// Example: Process player movement
async function processPlayerMovement(movementData) {
  const x402EnhancedData = await processGameData({
    type: 'player-move',
    payload: movementData
  });
  
  // Update player position with x402-enhanced data
  updatePlayerPosition(x402EnhancedData);
}

Unity (C#)

async void ProcessGameData(string eventType, object data)
{
    var gameData = new {
        Event = eventType,
        Data = data,
        Timestamp = System.DateTime.UtcNow,
        PlayerId = GetCurrentPlayerId()
    };
    
    var result = await Gx402Manager.ProcessX402Data(gameData);
    
    // Apply x402 enhancements
    ApplyX402Enhancements(eventType, result);
}

Step 5: Add Data Synchronization

Enable real-time synchronization between players.

WebGL/JavaScript

// Sync game state across all players
async function syncGameState(stateKey, stateData) {
  try {
    await Gx402.sync(stateKey, {
      ...stateData,
      syncId: generateSyncId(),
      timestamp: Date.now(),
      playerId: getCurrentPlayerId()
    });
    
    console.log(`Synced state: ${stateKey}`);
  } catch (error) {
    console.error('Sync failed:', error);
  }
}

// Listen for updates from other players
function setupSyncListeners() {
  Gx402.subscribe('player-moves', (data) => {
    if (data.playerId !== getCurrentPlayerId()) {
      // Update other player's position
      updateOtherPlayerPosition(data.playerId, data.position);
    }
  });
  
  Gx402.subscribe('game-events', (data) => {
    // Handle other game events
    processGameEvent(data);
  });
}

// Example usage in game loop
function update() {
  // When player moves
  if (playerMoved) {
    syncGameState('player-moves', {
      playerId: getCurrentPlayerId(),
      position: playerPosition,
      rotation: playerRotation
    });
  }
}

Step 6: Implement Error Handling

Add robust error handling for production use.

// Global error handler for Gx402 operations
Gx402.on('error', (error) => {
  console.error('Gx402 error occurred:', error);
  
  // Log to your analytics
  logError(error);
  
  // Implement fallback behavior
  switch (error.type) {
    case 'NETWORK_ERROR':
      handleNetworkError(error);
      break;
    case 'AUTH_ERROR':
      reauthenticateUser();
      break;
    case 'SYNC_ERROR':
      queueSyncOperation(error.operation);
      break;
    default:
      console.warn('Unknown error type, continuing operation');
  }
});

// Function to handle network errors
function handleNetworkError(error) {
  // Queue operations for retry when network is available
  const offlineQueue = new Queue();
  
  // Listen for connection status
  window.addEventListener('online', () => {
    retryQueuedOperations();
  });
}

// Function to retry queued operations
async function retryQueuedOperations() {
  while (!offlineQueue.isEmpty()) {
    const operation = offlineQueue.dequeue();
    try {
      await operation();
    } catch (error) {
      // Re-queue if still failing
      offlineQueue.enqueue(operation);
    }
  }
}

Step 7: Testing Your Integration

Test Scenarios

Basic Functionality
- Initialize the SDK
- Process simple data through x402
- Verify authentication works
Sync Functionality
- Multiple clients connecting
- Data synchronization between clients
- Offline/online transitions
Performance
- SDK initialization time
- x402 processing overhead
- Memory usage

Debugging Tips

// Enable detailed logging
Gx402.configure({
  debug: true,
  logLevel: 'verbose',
  captureMetrics: true
});

// Monitor performance
const metrics = Gx402.getMetrics();
console.log('SDK Performance:', {
  avgProcessTime: metrics.processTime.avg,
  syncSuccessRate: metrics.syncSuccessRate,
  networkLatency: metrics.network.latency
});

Step 8: Production Setup

When deploying to production:

Update Configuration

const Gx402 = new Gx402SDK({
  apiKey: process.env.Gx402_PROD_KEY, // Use environment variables
  environment: 'production',
  enableRealtimeSync: true,
  debug: false // Important: disable debugging in production
});

Security Considerations
- Never hardcode API keys in client code
- Use environment variables or secure token management
- Implement proper access controls
Performance Optimization
- Reduce debug logging
- Optimize sync frequency
- Implement smart caching

Troubleshooting

Common Issues

SDK Not Initializing

Check your API key is valid
Verify network connectivity
Ensure correct environment configuration

Sync Not Working

Confirm real-time sync is enabled
Check authentication status
Verify proper event listeners are set up

High Latency

Optimize sync frequency
Batch multiple operations
Consider regional endpoints

Next Steps

Now that you have the basic integration working:

Explore advanced features in the Features Documentation
Check platform-specific guides in the Platform Documentation
Review the complete API Reference
Join our Community for support and updates

Complete Integration Example

Here’s a complete example showing all the pieces together:

import { Gx402SDK } from '@Gx402/web-sdk';

class GameIntegration {
  constructor() {
    this.Gx402 = null;
    this.playerId = null;
    this.isInitialized = false;
  }
  
  async initialize(apiKey, playerId) {
    try {
      this.Gx402 = new Gx402SDK({
        apiKey,
        environment: 'production',
        enableRealtimeSync: true,
        debug: false
      });
      
      await this.Gx402.init();
      await this.Gx402.authenticate(playerId, this.generateAuthToken(playerId));
      
      this.playerId = playerId;
      this.isInitialized = true;
      
      this.setupSyncListeners();
      this.setupErrorHandlers();
      
      console.log('Game integration with Gx402 completed successfully');
      return true;
    } catch (error) {
      console.error('Failed to initialize game integration:', error);
      return false;
    }
  }
  
  async processGameEvent(eventType, payload) {
    if (!this.isInitialized) {
      throw new Error('Game integration not initialized');
    }
    
    const x402Result = await this.Gx402.processX402Data({
      event: eventType,
      data: payload,
      timestamp: Date.now(),
      playerId: this.playerId
    });
    
    return x402Result;
  }
  
  async syncGameState(key, data) {
    if (!this.isInitialized) return;
    
    await this.Gx402.sync(key, {
      ...data,
      playerId: this.playerId,
      timestamp: Date.now()
    });
  }
  
  setupSyncListeners() {
    this.Gx402.subscribe('game-state', (data) => {
      if (data.playerId !== this.playerId) {
        this.applyRemoteGameState(data);
      }
    });
  }
  
  setupErrorHandlers() {
    this.Gx402.on('error', (error) => {
      console.error('Gx402 error:', error);
      // Implement error handling logic
    });
  }
  
  generateAuthToken(playerId) {
    // Implement your token generation logic
    return `token-for-${playerId}`;
  }
  
  applyRemoteGameState(data) {
    // Apply game state from other players
    console.log('Applying remote game state:', data);
  }
}

// Usage
const gameIntegration = new GameIntegration();
await gameIntegration.initialize('YOUR_API_KEY', 'player-123');

You now have a solid foundation for using the Gx402 SDK in your game!

Beginner

Advanced

⚠️ Developer Preview

​Basic Integration Tutorial

​Overview

​Prerequisites

​Step 1: Install the SDK

​For WebGL/JavaScript Projects

​For Unity Projects

​For Unreal Engine Projects

​Step 2: Initialize the SDK

​WebGL/JavaScript

​Unity (C#)

​Unreal Engine (C++)

​Step 3: Add User Authentication

​WebGL/JavaScript

​Unity (C#)

​Step 4: Implement x402 Data Processing

​WebGL/JavaScript

​Unity (C#)

​Step 5: Add Data Synchronization

​WebGL/JavaScript

​Step 6: Implement Error Handling

​Step 7: Testing Your Integration

​Test Scenarios

​Debugging Tips

​Step 8: Production Setup

​Troubleshooting

​Common Issues

​Next Steps

​Complete Integration Example

Basic Integration Tutorial

Overview

Prerequisites

Step 1: Install the SDK

For WebGL/JavaScript Projects

For Unity Projects

For Unreal Engine Projects

Step 2: Initialize the SDK

WebGL/JavaScript

Unity (C#)

Unreal Engine (C++)

Step 3: Add User Authentication

WebGL/JavaScript

Unity (C#)

Step 4: Implement x402 Data Processing

WebGL/JavaScript

Unity (C#)

Step 5: Add Data Synchronization

WebGL/JavaScript

Step 6: Implement Error Handling

Step 7: Testing Your Integration

Test Scenarios

Debugging Tips

Step 8: Production Setup

Troubleshooting

Common Issues

Next Steps

Complete Integration Example