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.

Installation

There are two ways to install the CrateBytes Unity SDK:

Method 1: Unity Package Manager (Recommended)

Open Unity Package Manager (Window > Package Manager)
Click the + button in the top-left corner
Select “Add package from git URL”
Enter the repository URL: https://github.com/CrateBytes/CrateBytes-UnitySDK.git
Click Add

Method 2: Manual Installation

Visit the CrateBytes Unity SDK GitHub repository
Download the latest release or clone the repository
Import the package into your Unity project

Setup After Installation

Add the CrateBytesSDK component to a GameObject in your scene
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}");
    }
});

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

​CrateBytes Unity SDK

​Installation

​Method 1: Unity Package Manager (Recommended)

​Method 2: Manual Installation

​Setup After Installation

​Configuration

​SDK Settings

​Logging

​Quick Start

​1. Setup

​2. Authentication

​3. Session Management

​4. Leaderboards

​5. Player Metadata

​Best Practices

​1. Session Management

​2. Error Handling

​3. Data Management

​4. Performance