Unity SDK

Welcome to the LicenseSpring Unity beta SDK! This guide will help you understand and use the Unity SDK sample application.

1. Introduction

Where to download?

LicenseSpring .Net SDK

What is the LicenseSpring Unity SDK?

The LicenseSpring Unity SDK is a software licensing solution that integrates with Unity projects. It enables you to:

• Activate and validate software licenses

• Manage floating licenses for concurrent usage

• Track license consumption and usage

• Implement offline (air-gapped) activation

• Store license data securely on the local device

• Generate hardware-based device fingerprints

This SDK was tested on .NET Standard 2.1 framework, ensuring compatibility with Unity's scripting backend and IL2CPP (Intermediate Language to C++) compilation.

What Does This Sample Demonstrate?

The UnitySample project is a fully functional demonstration that shows:

• How to initialize the SDK

• License activation with a license key

• License validation and checking

• License deactivation

• Floating license borrowing and release

• Consumption tracking for usage-based licenses

• Device variable management

• Working with local license file storage

This sample provides a complete UI that lets you test all these features interactively, and is easily expandable should you wish to test additional features yourself.

2. Prerequisites

Before you begin, ensure you have:

1. Unity Hub installed (download from https://unity.com/download)

2. Unity version 6000.2.9f1 (or a compatible version)

   • This is the Unity LTS (Long Term Support) version

   • You can install it through Unity Hub

   • This demo was created using this Unity version

3. LicenseSpring Account Credentials:

   • API Key

   • Shared Key

   • Product Code (create a product on the LicenseSpring platform)

4. These are provided by your LicenseSpring account administrator. You'll need to provide these in the Config.cs file (see Section 6).

5. Basic Unity knowledge is helpful but not required — this guide will walk you through the process of setting up the Unity sample step-by-step.

3. Opening the Project

1

Add the project to Unity Hub

• Launch Unity Hub

• Click the "Add" button → Add project from disk

• Navigate to the UnitySample folder:

Location: Your-download-location\LicenseSpring\UnitySample

• Click "Open" to add the project to Unity Hub

• Click on the project in Unity Hub to launch it with Unity Editor

2

First-Time Project Load

• The first time you open the project, Unity will import all assets. This may take a few minutes.

• You'll see a progress bar as Unity processes:

  • Scripts

  • DLL files

  • Scenes

  • Settings

3

Opening the Main Scene

• The sample project includes an editor script (DefaultSceneLoader.cs) that automatically opens the main scene (SampleScene.unity) when you first load the project.

• If you ever need to manually open the scene:

  1. In the Unity Editor, locate the Project window (bottom/right panel, next to the Console window)

  2. Navigate to: Assets > Scenes

  3. Double-click "SampleScene.unity"

4. Project Structure

UnitySample/
├── Assets/
│   ├── Plugins/
│   │   └── LicenseSpring/         ← SDK DLLs LOCATED HERE (IMPORTANT!)
│   ├── Scripts/                   ← Application scripts
│   ├── Scenes/                    ← Unity scenes
│   │   └── SampleScene.unity      ← Main scene
│   ├── Settings/                  ← Unity render pipeline settings
│   └── LicenseSpringLogo.png      ← LicenseSpring logo asset
├── ProjectSettings/               ← Unity project configuration
├── Packages/                      ← Unity package manifest
└── Build/                         ← Build output directory

SDK DLL Location

LicenseSpring SDK DLL and dependencies are located in Assets/Plugins/LicenseSpring/

This folder contains:

• LicenseSpring.dll — The main SDK library with all licensing functionality

• LicenseSpring.xml — API documentation for IntelliSense in Visual Studio

• hardware_id_generator.dll — Native library for generating hardware-based device fingerprints

The HWID generator file is OS dependent; the sample uses a Windows x64 version. If you're running on another OS you need to replace this file with a corresponding version distributed with the SDK.

• Other assorted required dlls

Scripts Organization

The Assets/Scripts/ folder contains the application logic:

• Config.cs - SDK configuration and credentials

• LicenseSpringManager.cs - SDK lifecycle and license operations

• LicenseManagementUI.cs - Activation/deactivation UI controller

• LicenseDetailsUI.cs - License information display

• ProductDetailsUI.cs - Product information display

• Editor/DefaultSceneLoader.cs - Auto-loads scene on project open

5. Script Architecture

Understanding how the scripts work together:

Config.cs - Configuration and Credentials

This static class holds your LicenseSpring credentials and configuration:

• ApiKey: Your LicenseSpring API key

• SharedKey: Your shared secret key for encryption

• ProductCode: Your product identifier

The CreateConfiguration() method:

• Builds a Configuration object with your credentials

• Sets up ExtendedOptions (logging, network info, file paths, etc.)

• Returns a ready-to-use configuration

You'll modify this file to add your own credentials.

LicenseSpringManager.cs - SDK Lifecycle Manager

This is the core singleton manager that handles all SDK operations.

Key responsibilities:

• Initializes the SDK on application startup

• Provides a global access point via Instance property

• Manages license activation and deactivation

• Handles local license file operations

Important methods:

• InitializeSdk() - Initializes SDK (called automatically)

• ActivateLicense(key) - Activates a license with provided key

• DeactivateCurrentLicense() - Deactivates the active license

• ClearLocalStorage() - Deletes local license files

• GetDataLocation() - Returns license file storage path

• IsInitialized - Property to check if SDK is ready

Singleton pattern: Only one instance exists throughout the application lifecycle. Access it via: LicenseSpringManager.Instance

This is not mandatory; you could also instantiate multiple managers and handle multiple licences concurrently. Just make sure you only use one manager instance per license to avoid issues.

LicenseManagementUI.cs - License Operations UI

This script controls the top portion of the UI for license operations.

UI Elements:

• License key input field

• Local files path display

• Activate button

• Deactivate button

• Delete local files button

Key functionality:

• Collects license key input from user

• Triggers activation/deactivation operations

• Updates the local file path display

• Communicates with LicenseDetailsUI to refresh license info

LicenseDetailsUI.cs - License Information Display

This script displays comprehensive license information and provides additional license operations.

Displayed information:

• License key and type

• License status and validity

• Offline activation status

• Trial information

• Validity period and remaining days

• Grace period and maintenance period

• Last check timestamp

• Floating license details

• Consumption tracking (for usage-based licenses)

• Device variables

Interactive features:

• Check License — Validates license with server

• Borrow License — Borrows a floating license for offline use

• Sync Consumption — Syncs usage data with server

• Update Consumption — Updates local consumption value

• Add Device Variable — Adds test device-specific data

ProductDetailsUI.cs - Product Information Display

This script fetches and displays product information.

Displayed information:

• Product name

• Product code

• Trial allowed (yes/no)

• Trial period duration (in days)

• Authorization type (license key, user-based, etc.)

Functionality:

• Loads product details from the SDK

• Displays them in the UI

How They Work Together

Flow:

1. Unity starts → LicenseSpringManager.Awake() is called
   ↓
2. LicenseSpringManager.InitializeSdk() initializes the SDK with Config data
   ↓
3. UI scripts wait for initialization (using coroutines)
   ↓
4. Once initialized, ProductDetailsUI loads product information
   ↓
5. User enters license key in LicenseManagementUI
   ↓
6. User clicks "Activate" → LicenseManagementUI.OnActivateClicked()
   ↓
7. LicenseManagementUI calls LicenseSpringManager.ActivateLicense(key)
   ↓
8. On success, LicenseDetailsUI.UpdateLicenseInfo() refreshes the display
   ↓
9. User can now perform various operations (check, deactivate, borrow, etc.)

6. Configuration

To use the SDK with your own LicenseSpring account, you need to update the credentials in Config.cs.

1

Opening Config.cs

• In Unity Editor, go to the Project window

• Navigate to: Assets > Scripts > Config.cs

• Double-click to open in your code editor (Visual Studio or your preferred IDE)

2

What to Update

Replace these values with your own credentials:

private static readonly string ApiKey = "YOUR_API_KEY_HERE";
private static readonly string SharedKey = "YOUR_SHARED_KEY_HERE";
private static readonly string ProductCode = "YOUR_PRODUCT_CODE_HERE";

3

Where to Get These Values

Log in to your LicenseSpring account at:

https://saas.licensespring.com/

Navigate to: Settings -> Keys

You'll find your API and Shared Key here.

Hardware ID Algorithm Options

The SDK supports multiple algorithms for generating device fingerprints. In CreateExtendedOptions() you'll see:

options.DeviceIdAlgorithm = LicenseSpring.DeviceIDAlgorithm.HardwareIdGeneratorWindowsHardwareFingerprintId;

Available options:

• HardwareIdGeneratorWindowsHardwareFingerprintId (recommended for Windows)

• HardwareIdGeneratorWindowsUuid

• HardwareIdGeneratorMacOSSerialNumber

• HardwareIdGeneratorMacOSPlatformUuid

• Multiple legacy algorithms

Choose the one that best fits your target platform(s).

Local License File Storage

The SDK stores activated licenses locally in encrypted files. The storage location is configured in ExtendedOptions:

options.LicenseFilePath = @"C:\Users\Username\AppData\Local\LicenseSpring\unity";

You can customize this path to any location. On different platforms, Unity will adjust the path accordingly:

• Windows: C:\Users\[Username]\AppData\Local\LicenseSpring\unity

• macOS: ~/Library/Application Support/LicenseSpring/unity

• Linux: ~/.local/share/LicenseSpring/unity

Note: Use Unity's Application.persistentDataPath for cross-platform compatibility:

options.LicenseFilePath = System.IO.Path.Combine(Application.persistentDataPath, "LicenseSpring");

7. Running the Sample

How to Enter Play Mode

1

Start the sample

• Ensure SampleScene.unity is open (it should load automatically)

• Click the Play button at the top center of the Unity Editor

• The Game view will activate and show the sample application UI

2

What Happens on Initialization

When you press Play, here's what happens behind the scenes:

1. Unity instantiates all GameObjects in the scene

2. LicenseSpringManager.Awake() is called immediately

3. InitializeSdk() runs, setting up the SDK with your configuration

4. UI scripts wait for initialization to complete

5. ProductDetailsUI loads and displays product information

6. The UI becomes interactive and ready for license operations

You'll see log messages in the Unity Console window showing the initialization progress.

UI Walkthrough

The sample UI is organized into several sections:

PRODUCT DETAILS

• Product Name

• Product Code

• Trial Allowed

• Trial Period

• Authorization Type

LICENSE MANAGEMENT

• License Key Input Field

• [Activate] [Deactivate] buttons

• Local Files Path Display

• [Delete Local Files] button

LICENSE DETAILS

• License Key

• License Type

• License Status

• Offline Activation Status

• Validity Period

• Days Remaining

• Last Checked

• Is Trial

• Floating License Info

• [Check License] [Borrow License] buttons

CONSUMPTION TRACKING (for usage-based licenses)

• Total Consumption

• Max Consumption

• [Sync Consumption] [Update Consumption] buttons

DEVICE VARIABLES

• Display of device-specific key-value pairs

• [Add Device Variable] button

To stop the sample: Click the Stop button to exit Play mode.

8. Testing Scenarios

This section provides step-by-step walkthroughs for testing different licensing scenarios.

SCENARIO 1: Basic Online Activation

This is the most common scenario — activating a license with internet access.

1

• Click Play in Unity Editor to run the sample

• Wait for the SDK to initialize (you'll see product details populate)

2

• In the "License Key" input field, enter your test license key (You should have received this from your LicenseSpring account)

• Click the [Activate] button

3

If successful, you'll see:

• License details populate with information

• License status shows "Active"

• Validity period and expiration date display

• Days remaining shows the time left on the license

• Check the Unity Console for detailed log messages

What to Observe:

• The license file is saved locally (path shown in "Local Files Path")

• The activated license persists between Play mode sessions

• Product features and restrictions are now enforced

---

SCENARIO 2: License Checking and Validation

After activating a license, you can validate it with the server.

1

• Ensure you have an activated license (see Scenario 1)

• Click the [Check License] button in the License Details section

2

• The SDK will contact the LicenseSpring server to validate:

  • License is still active

  • License hasn't been revoked

  • Device is still authorized

  • Any policy changes from the server

• If valid, the license details refresh with updated information

• The "Last Checked" timestamp updates to the current time

What This Does:

• Validates that the license is still active server-side

• Ensures the license hasn't been transferred to another device or disabled

• Syncs any server-side changes

• Updates local license data with latest server information

When to Use:

• Periodically during application runtime (e.g., daily)

• When up to date server information is needed (e.g., floating licensing)

• Before enabling premium features

• After significant time offline

---

SCENARIO 3: License Deactivation

Deactivating a license frees up an activation slot and removes local data.

1

• Ensure you have an activated license (see Scenario 1)

• Click the [Deactivate] button in the License Management section

2

The SDK will:

• Contact the server to release the activation

• Delete the local license file

• Clear all license information from the UI

• The activation slot is now available for another device

3

• All license details fields will become empty

• Click the [Delete local files] button

What to Observe:

• The local license file is deleted (verify by checking the file path)

• The device is no longer counted against the max activations

• You can activate a different license key now

Use Cases:

• Transferring license to another device

• Testing different license configurations

• End of license period

• Application uninstallation

---

SCENARIO 4: Floating License Borrowing/Release

Floating licenses allow temporary offline usage by "borrowing" a license.

Prerequisites:

• Your license must be a floating license type

• The license must have borrowing enabled

1

Steps to Borrow

• Activate a floating license (see Scenario 1)

• Click the [Borrow License] button

• The SDK will reserve this license for your device

• You can now use the application offline for the borrow period

• The "Floating" status will indicate "Borrowed"

2

Steps to Release (Return)

• Click the [Borrow License] button again (it acts as a toggle)

• The SDK returns the license to the floating pool

• The license slot is now available for other concurrent users

What This Enables:

• Temporary offline usage

• Predetermined borrow period (configured in your LicenseSpring account)

• Ensures license returns to pool when no longer needed

Floating License Timeout: If you don't interact with the application, the floating license will automatically timeout and return to the pool.

---

SCENARIO 5: Consumption Tracking

For usage-based licensing (e.g., API calls, credits, processing time).

Prerequisites:

• Your license must be configured for consumption tracking

• The license must have a max consumption value set

1

Steps to Update Consumption

• Activate a license with consumption tracking enabled

• In the Consumption section, note the "Total Consumption" and "Max Consumption"

• Click [Update Consumption] button

• The local consumption value increments (simulating usage)

• The "Total Consumption" field updates to reflect the new value

2

Steps to Sync Consumption

• Click [Sync Consumption] button

• The SDK sends the accumulated consumption data to the server

• The server validates against the max consumption limit

• If within limits, the sync succeeds

• If over limit, the license may be restricted (depending on policy)

What to Observe:

• Consumption persists locally until synced

• The SDK can operate offline and sync later

• Server-side reporting shows usage analytics

Use Cases:

• API call credits

• Processing time tracking

• Feature usage limits

• Pay-per-use models

---

SCENARIO 6: Device Variables

Device variables are custom key-value pairs stored with the license on the device.

1

• Activate a license (see Scenario 1)

• Click [Add Device Variable] button

• A test device variable is added

• The device variable appears in the Device Variables display section

• Device variables persist locally with the license file

What This Enables:

• Store device-specific configuration

• Track custom data per installation

• Implement feature flags per device

• Debug and support purposes

---

SCENARIO 7: Working with Local License Files

Understanding how local license storage works.

1

Viewing Local Files Path

• Run the sample in Play mode

• Look at the "Local Files Path" display in License Management section

• Note the path (e.g., C:\Users\[Username]\AppData\Local\LicenseSpring\[ProductKey])

2

Inspecting License Files

• Exit Play mode

• Open Windows Explorer (or Finder on macOS)

• Navigate to the path shown

• You'll see encrypted license file (.lic)

3

Deleting Local Files

• In Play mode, click [Delete Local Files] button

• License file in that directory is removed

• The application returns to an unlicensed state

• You'll need to activate again to use the application

4

Testing Offline Behavior

• Activate a license while online

• Stop Play mode

• Disconnect from the internet

• Start Play mode again

• The SDK loads the license from the local file

• The application works offline (within grace period limits)

What to Observe:

• License files are encrypted

• Files persist between Play mode sessions

• Deleting files doesn't deactivate server-side (the activation slot remains used)

• To properly deactivate, always use the [Deactivate] button first

9. Customization Guide

How to Integrate the SDK into Your Own Unity Project

This section explains how to take the LicenseSpring SDK and integrate it into your own Unity application.

Step 1: Copy the DLLs Folder

• In your UnitySample project, locate:

Assets/Plugins/LicenseSpring/

• Copy the entire LicenseSpring folder

• In your own Unity project, paste it into:

Assets/Plugins/LicenseSpring/

Unity automatically recognizes DLLs in the Plugins folder. Just drag and drop them in the folder and wait for Unity to initialize the files.

It's possible you will need additional dlls not included with this demo, or that not all DLLs are needed; this depends on your specific SDK usage.

Step 2: Create Your Own Configuration

Create a new C# script in your project (e.g., MyLicenseConfig.cs) and add your LicenseSpring credentials:

public static class MyLicenseConfig
{
    private static readonly string ApiKey = "YOUR_API_KEY";
    private static readonly string SharedKey = "YOUR_SHARED_KEY";
    private static readonly string ProductCode = "YOUR_PRODUCT_CODE";

    public static LicenseSpring.Configuration CreateConfiguration()
    {
        var config = new LicenseSpring.Configuration(
            apiKey: ApiKey,
            sharedKey: SharedKey,
            productCode: ProductCode,
            appName: "YourAppName",
            appVersion: "1.0.0",
            extendedOptions: CreateExtendedOptions()
        );
        return config;
    }
    private static LicenseSpring.ExtendedOptions CreateExtendedOptions()
    {
        var options = new LicenseSpring.ExtendedOptions();
        options.CollectNetworkInfo = true;
        options.EnableLogging = true;
        options.DeviceIdAlgorithm = LicenseSpring.DeviceIDAlgorithm.HardwareIdGeneratorWindowsHardwareFingerprintId;
        // Any additional options
        return options;
    }
}

Customize ExtendedOptions as needed (logging, file paths, etc.)

Step 3: Initialize the SDK

Create a manager script that initializes the SDK when your application starts:

using LicenseSpring;
using UnityEngine;

public class MyLicenseManager : MonoBehaviour
{
    private ILicenseManager licenseManager;

    void Awake()
    {
        // Initialize SDK
        var config = MyLicenseConfig.CreateConfiguration();
        licenseManager = LicenseManager.GetInstance();
        licenseManager.Initialize(config);

        Debug.Log("LicenseSpring SDK initialized!");
    }

    public void ActivateLicense(string licenseKey)
    {
        try
        {
            var license = licenseManager.ActivateLicense(licenseKey);
            Debug.Log("License activated: " + license.GetLicenseKey());
        }
        catch (System.Exception ex)
        {
            Debug.LogError("Activation failed: " + ex.Message);
        }
    }

    public bool IsLicenseValid()
    {
        var license = licenseManager.CurrentLicense();
        return license != null && license.IsActive();
    }
}

Attach this script to a GameObject in your scene (e.g., a "LicenseManager" empty GameObject).

Step 4: Implement License Checking in Your Application Flow

Decide where in your application you want to check the license:

• On application startup (in Awake or Start)

• Before enabling premium features

• Periodically during runtime

• Before critical operations

Example: Check license before starting the main application:

public class ApplicationController : MonoBehaviour
{
    public MyLicenseManager licenseManager;

    void Start()
    {
        if (licenseManager.IsLicenseValid())
        {
            // Start main application
            LoadMainMenu();
        }
        else
        {
            // Show license activation UI
            ShowActivationDialog();
        }
    }
}

Step 5: Persistence Considerations

The SDK automatically handles license persistence through local files. However, consider:

• Where to store license files (use Application.persistentDataPath)

• How often to check with the server (balance security vs. performance)

• Grace period configuration (allow temporary offline usage)

• How to handle license expiration gracefully in your UX

Example of configuring file path:

var options = new LicenseSpring.ExtendedOptions();
options.LicenseFilePath = System.IO.Path.Combine(
    Application.persistentDataPath,
    "LicenseSpring"
);

Best Practices

1. Initialize Early

   • Initialize the SDK as early as possible in your application lifecycle

   • Use Awake() or a [RuntimeInitializeOnLoadMethod] for earliest execution

2. Handle Exceptions Gracefully

   • Wrap SDK calls in try-catch blocks

   • Provide user-friendly error messages

   • Log detailed errors for troubleshooting

3. Check Licenses Periodically

   • Don't just check once at startup

   • Periodically validate with the server

4. Respect Offline Grace Periods

   • Allow users to work offline within configured grace periods

   • Only enforce strict checks when online

   • Provide clear messaging when license checks fail

5. Test Different Scenarios

   • Test online activation

   • Test offline behavior

   • Test license expiration

   • Test max activations reached

   • Test invalid license keys

6. Provide Clear User Feedback

   • Display clear error messages

   • Explain why activation failed

   • Provide support contact information

7. Build Platform Considerations

   • Test on each target platform (Windows, macOS, Linux, Android, iOS)

   • Verify file paths work cross-platform

   • Ensure hardware ID generation works on all platforms

   • Test IL2CPP builds (not just Mono)

10. Additional Information

SDK Documentation

The LicenseSpring.xml file in Assets/Plugins/LicenseSpring/ contains complete API documentation. This enables IntelliSense in Visual Studio and Rider.

To view API docs:

1. Open your C# script in Visual Studio

2. Type LicenseSpring. and IntelliSense will show available classes

3. Hover over methods to see parameter descriptions and return types

Main SDK Documentation

For comprehensive documentation, visit:

https://docs.licensespring.com/

Topics covered:

• SDK installation and setup

• Advanced features (SSO, consumption, floating licenses)

• Best practices

• API reference

• Platform-specific guides

Support

If you need assistance:

1. Check the documentation at: https://docs.licensespring.com/

2. Contact LicenseSpring Support:

   • https://licensespring.zendesk.com/hc/en-us/requests/new

Include:

• Unity version

• Error messages from Console

• Platform (Windows, macOS, etc.)

• Steps to reproduce the issue

Please be as detailed as possible.

Sample Project Updates

The UnitySample project is maintained as part of the LicenseSpring .NET SDK repository. Check for updates periodically to get:

• Bug fixes

• New feature demonstrations

• Performance improvements

• Unity version updates

Final Notes

Congratulations! You now have a comprehensive understanding of the LicenseSpring Unity SDK and the UnitySample project.

The LicenseSpring SDK provides powerful and flexible licensing for Unity applications. Take advantage of its features to protect your software and provide a great experience for your users.

Happy licensing! 🎉