Unity 3D / Mono
In this post we have summarized the necessary steps to add software licensing into a Unity game. Unity uses Mono runtime, which means that a special version of our .NET client library can be used.
We recommend to read the Considerations section in the end of the tutorial that can help when troubleshooting common errors.
To implement license key verification a Unity game, we can use a special build of the client library for .NET that is platform independent. You can download it here. Make sure to reference the binary with the name
Cryptolens.Licensing.CrossPlatform.dll. You can also install it through NuGet.
A note about Newtonsoft.Json
Cryptolens.Licensing.CrossPlatform depends on the
Newtonsoft.Json library. In earlier versions of Unity, the
Newtonsoft.Json.dll had to be included alongside the
Cryptolens.Licensing.CrossPlatform.dll file (it is provided in the same zip file as our library).
In later versions (from our tests, since 2020.3.16f1), Unity added Newtonsoft.Json as an internal package, meaning that it no longer needs to be included in the Asset folder. However, depending on the Newtonsoft.Json version used by Unity, you may have to recompile our library to target that version. In sum, there are three cases:
If Unity does not have an internal Newtonsoft.Json package
This is the case for older versions of Unity (from our tests, for versions earlier than 2020.3.16f1). In this case, you need to include both
If Unity uses Newtonsoft.Json v12
In this case, we recommend using the .NET Framework 4.8 binary (in the net48 folder) without including the
If Unity uses Newtonsoft.Json v13
In this case, our library needs to be recompiled with a few changes. The steps are as follows:
- Step 1: Install the .NET SDK.
- Step 2: Clone the repository or download the zip file.
- Step 3: In the Cryptolens.Licensing folder, open
Cryptolens.Licensing.CrossPlatform.csproj. Remove the following lines:
... <SignAssembly>true</SignAssembly> <DelaySign>false</DelaySign> <AssemblyOriginatorKeyFile>certifikat.pfx</AssemblyOriginatorKeyFile> ...
- Step 4: Change Newtonsoft.Json version from
13.0.1in the section below:
<ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'net47' or '$(TargetFramework)' == 'net471' or '$(TargetFramework)' == 'net48'"> <PackageReference Include="Newtonsoft.Json" Version="12.0.3" /> </ItemGroup>
- Step 5: Go back to the main folder (with
slnfiles) and run the following command:
dotnet build Cryptolens.Licensing.CrossPlatform.sln.
- Step 6: Navigate to
Cryptolens.Licensing\bin\Release\net48) and copy the
Cryptolens.Licensing.CrossPlatform.dllinto the assets folder.
If you have any questions, please reach out to us at [email protected].
License key verification
Once you have the binaries, we can get license key verification up and running quite quickly. We assume that already have an account and a product. There are just two things left:
- Add the Cryptolens.Licensing.dll and in some cases Newtonsoft.Json.dll into the Assets folder (please check out the section earlier when Newtonsoft.Json needs to be included).
- Include the license key verification logic.
Note: we recommend to avoid using Key.Activate that takes in an ActivateModel since signature verification will not work on some platforms. Instead, we recommend to use a special version of Key.Activate as shown below:
// call to activate var result = Key.Activate(token: auth, productId: 3349, key: "GEBNC-WZZJD-VJIHG-GCMVD", machineCode: "foo"); // obtaining the license key (and verifying the signature automatically). var license = LicenseKey.FromResponse("RSAPubKey", result);
Also, when implementing offline verification, please call
LoadFromString with the RSAPubKey. The format of the license file should be set to Other languages (see more here) when downloading it in the dashboard or using Activation Forms.
You can download a sample project here.
Other licensing models
Since Unity uses C# as the scripting interface, you can use all of the .NET examples provided in this wiki. As a next step, please take a look at the available licensing models.
Please keep in mind if you use the version of Key.Activate that was suggested earlier,
you would need to create a license key object from the response such as
LicenseKey.FromResponse(result).SaveToFile() to be able to use the extension methods, eg.
result.LicenseKey.SaveToFile() will not work.
IsOnRightMachine() methods require root access on Linux. If you are using Unity with IL2CCP,
Helpers.GetMacAddress() can be a better alternative, since other methods may throw an error.
Some users who build and then run the unity project may get a null response from
Key.Activate, which will be treated as if the license key is invalid. We recommend to set API Compatibility level to .NET 4.x in Edit > Project Settings > Player > Other Settings > API Compatibility Level. In this case, the the binaries for .NET 4.* need to be used, i.e. not the .NET Standard version.