Unity SDK

licensespring unity sdk beta beginner's guide 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? https //sdk licensespring com/ net/v7 37 1 unity1/licensespring netsdk v7 37 1 unity1 zip 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 unity hub installed (download from https //unity com/download ) 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 licensespring account credentials api key shared key product code (create a product on the licensespring platform) these are provided by your licensespring account administrator you'll need to provide these in the config cs file (see section 6) 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 instructions 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 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 automatic scene loading the sample project includes a helpful editor script ( defaultsceneloader cs ) that automatically opens the main scene ( samplescene unity ) when you first load the project you don't need to manually locate and open the scene! if you ever need to manually open the scene in the unity editor, locate the project window (bottom/right panel, next to the console window) navigate to assets > scenes double click "samplescene unity" 4\ project structure the unitysample project is organized as follows 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 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 any 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 here's the flow of how these scripts interact 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 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) 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"; 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 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 what happens on initialization when you press play, here's what happens behind the scenes unity instantiates all gameobjects in the scene licensespringmanager awake() is called immediately initializesdk() runs, setting up the sdk with your configuration ui scripts wait for initialization to complete productdetailsui loads and displays product information 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 steps click play in unity editor to run the sample wait for the sdk to initialize (you'll see product details populate) in the "license key" input field, enter your test license key (you should have received this from your licensespring account) click the \[activate] button 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 steps ensure you have an activated license (see scenario 1) click the \[check license] button in the license details section 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 in another way 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 steps ensure you have an activated license (see scenario 1) click the \[deactivate] button in the license management section 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 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 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" 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 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 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 steps 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 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] ) 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) 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 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 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) 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 the 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 ) 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 open your c# script in visual studio type "licensespring " and intellisense will show available classes 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 check the documentation at https //docs licensespring com/ 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! 🎉