Skip to content

README.md

Latest commit

 

History

History
349 lines (273 loc) · 9.3 KB

README.md

File metadata and controls

349 lines (273 loc) · 9.3 KB

CrateBytes Unity SDK

A comprehensive Unity SDK for integrating CrateBytes backend services into your games. This SDK provides authentication, session management, leaderboards, and player metadata functionality.

Features

  • Authentication: Guest and Steam authentication support
  • Session Management: Automatic session tracking with heartbeat
  • Leaderboards: Submit scores and retrieve leaderboard data
  • Player Metadata: Store and retrieve player-specific data
  • Unity Integration: Built specifically for Unity with coroutine support
  • Error Handling: Comprehensive error handling and logging

Installation

  1. Import the CrateBytes SDK package into your Unity project
  2. Add the CrateBytesSDK component to a GameObject in your scene
  3. Configure the SDK with your project's base URL and public key

Configuration

SDK Settings

The SDK can be configured through the Inspector or via code:

// Configure via code
CrateBytesSDK.Instance.Initialize("https://api.cratebytes.com/api/game", "your-public-key");

Logging

The SDK includes a built-in logging system that can be enabled/disabled:

Via Inspector:

  • Select the GameObject with the CrateBytesSDK component
  • Check/uncheck the "Enable Logging" field

Via Code:

// Enable logging
CrateBytesSDK.Instance.enableLogging = true;

// Or use the logger directly
CrateBytesLogger.Enabled = true;

// Disable logging (recommended for production)
CrateBytesLogger.Enabled = false;

Note: Logging is disabled by default for production builds. Enable only when debugging.

Quick Start

1. Setup

Add the SDK component to your scene:

// The SDK will automatically create a singleton instance
var sdk = CrateBytesSDK.Instance;

// Configure with your project settings
sdk.Initialize("https://api.cratebytes.com/api/game", "your-public-key");

2. Authentication

// Guest authentication
yield return CrateBytesSDK.Instance.Auth.GuestLogin(null, (response) =>
{
    if (response.Success)
    {
        Debug.Log($"Authenticated! Player ID: {response.Data.playerId}");
    }
});

// Steam authentication
yield return CrateBytesSDK.Instance.Auth.SteamLogin("steam-auth-ticket", (response) =>
{
    if (response.Success)
    {
        Debug.Log($"Steam authenticated! Player ID: {response.Data.playerId}");
    }
});

3. Session Management

// Start a session
yield return CrateBytesSDK.Instance.Session.StartSession((response) =>
{
    if (response.Success)
    {
        Debug.Log("Session started!");
        // Start automatic heartbeat
        CrateBytesSDK.Instance.StartHeartbeat();
    }
});

// Stop session when done
yield return CrateBytesSDK.Instance.Session.StopSession();

4. Leaderboards

// Submit a score
yield return CrateBytesSDK.Instance.Leaderboard.SubmitScore("leaderboard-id", "1000", (response) =>
{
    if (response.Success)
    {
        Debug.Log("Score submitted!");
    }
});

// Get leaderboard entries
yield return CrateBytesSDK.Instance.Leaderboard.GetLeaderboard("leaderboard-id", 1, (response) =>
{
    if (response.Success)
    {
        foreach (var entry in response.Data.entries)
        {
            Debug.Log($"Player {entry.player.playerId}: {entry.score}");
        }
    }
});

5. Player Metadata

// Define your player data structure
[Serializable]
public class PlayerData
{
    public int Level { get; set; }
    public int Experience { get; set; }
    public string[] Achievements { get; set; }
}

// Save player data
var playerData = new PlayerData
{
    Level = 5,
    Experience = 1250,
    Achievements = new[] { "FirstWin", "SpeedRunner" }
};

yield return CrateBytesSDK.Instance.Metadata.SetPlayerDataObject(playerData, (response) =>
{
    if (response.Success)
    {
        Debug.Log("Player data saved!");
    }
});

// Retrieve player data
yield return CrateBytesSDK.Instance.Metadata.GetPlayerData<PlayerData>((response) =>
{
    if (response.Success && response.Data != null)
    {
        Debug.Log($"Level: {response.Data.Level}, XP: {response.Data.Experience}");
    }
});

API Reference

CrateBytesSDK

Main SDK class that manages all services.

Properties

  • Auth: Authentication service
  • Session: Session management service
  • Leaderboard: Leaderboard service
  • Metadata: Player metadata service

Methods

  • Initialize(string baseUrl, string publicKey): Configure the SDK
  • IsConfigured(): Check if SDK is properly configured
  • StartHeartbeat(): Start automatic session heartbeat
  • StopHeartbeat(): Stop automatic session heartbeat

Authentication Service

Handles user authentication.

Methods

  • GuestLogin(string playerId, Action<CrateBytesResponse<AuthResponse>> callback): Authenticate as guest
  • SteamLogin(string steamAuthTicket, Action<CrateBytesResponse<AuthResponse>> callback): Authenticate with Steam
  • IsAuthenticated(): Check if user is authenticated
  • GetAuthToken(): Get current auth token
  • Logout(): Clear authentication

Session Service

Manages player sessions.

Methods

  • StartSession(Action<CrateBytesResponse<SessionData>> callback): Start a new session
  • Heartbeat(Action<CrateBytesResponse<SessionData>> callback): Send heartbeat
  • StopSession(Action<CrateBytesResponse<SessionData>> callback): Stop current session
  • IsSessionActive(): Check if session is active
  • GetCurrentSession(): Get current session data

Leaderboard Service

Handles leaderboard operations.

Methods

  • GetLeaderboard(string leaderboardId, int page, Action<CrateBytesResponse<LeaderboardResponse>> callback): Get leaderboard entries
  • SubmitScore(string leaderboardId, string score, Action<CrateBytesResponse<ScoreSubmissionResponse>> callback): Submit a score

Metadata Service

Manages player data.

Methods

  • GetPlayerData(Action<CrateBytesResponse<PlayerDataResponse>> callback): Get current player data
  • GetPlayerDataBySequentialId(int sequentialId, Action<CrateBytesResponse<PlayerDataResponse>> callback): Get player data by ID
  • SetPlayerData(string data, Action<CrateBytesResponse<PlayerDataResponse>> callback): Set player data as string
  • SetPlayerDataObject(object data, Action<CrateBytesResponse<PlayerDataResponse>> callback): Set player data as object
  • DeletePlayerData(Action<CrateBytesResponse<string>> callback): Delete player data
  • GetPlayerData<T>(Action<CrateBytesResponse<T>> callback): Get player data as specific type

Data Structures

AuthResponse

public class AuthResponse
{
    public string token { get; set; }
    public string playerId { get; set; }
    public int sequentialId { get; set; }
    public string steamId { get; set; }
}

SessionData

public class SessionData
{
    public string id { get; set; }
    public string playerId { get; set; }
    public DateTime startTime { get; set; }
    public DateTime lastHeartbeat { get; set; }
    public DateTime? endTime { get; set; }
}

LeaderboardResponse

public class LeaderboardResponse
{
    public LeaderboardInfo leaderboard { get; set; }
    public LeaderboardEntry[] entries { get; set; }
    public int totalEntries { get; set; }
    public int pages { get; set; }
}

Error Handling

All API calls return a CrateBytesResponse<T> object with the following structure:

public class CrateBytesResponse<T>
{
    public int StatusCode { get; set; }
    public T Data { get; set; }
    public CrateBytesError Error { get; set; }
    public bool Success { get; set; }
}

Always check the Success property before using the Data:

yield return CrateBytesSDK.Instance.Auth.GuestLogin(null, (response) =>
{
    if (response.Success)
    {
        // Use response.Data safely
        Debug.Log($"Player ID: {response.Data.playerId}");
    }
    else
    {
        // Handle error
        Debug.LogError($"Error: {response.Error?.Message}");
    }
});

Best Practices

1. Session Management

  • Always start a session when the player begins playing
  • Use automatic heartbeat to keep sessions alive
  • Stop sessions when the player stops playing or the app is paused

2. Error Handling

  • Always check response success before using data
  • Implement retry logic for network failures
  • Log errors for debugging

3. Data Management

  • Use strongly-typed data structures for player metadata
  • Validate data before sending to the server
  • Handle data serialization errors gracefully

4. Performance

  • Use coroutines for all API calls
  • Don't make too many requests simultaneously
  • Cache frequently accessed data locally

Configuration

Configure the SDK in the Unity Inspector or programmatically:

// Inspector configuration
[SerializeField] private string baseUrl = "https://api.cratebytes.com/api/game";
[SerializeField] private string publicKey = "your-public-key";
[SerializeField] private float heartbeatInterval = 60f; // 1 minute
[SerializeField] private float sessionTimeout = 300f; // 5 minutes

// Programmatic configuration
CrateBytesSDK.Instance.Initialize(baseUrl, publicKey);

Dependencies

  • Unity 2020.3 or later
  • Newtonsoft.Json (included in package)

Support

For support and documentation, visit:

License

This SDK is provided by CrateBytes for integration with the CrateBytes backend service.