The shape of the integration
One UGameInstanceSubsystem owns the license state. On Initialize it loads the stored key, sends POST /v1/licenses/validate through FHttpModule, and sets a state from the answer. The request is asynchronous, so the game keeps rendering while it waits. When there is no usable answer, the subsystem verifies the stored token instead. That code is on the offline verification page. First-run activation is on the activation page.
The snippets follow the Unreal Engine 5.0 API reference. I did not compile them in an engine project for this page.
Module setup
// MyGame.Build.cs
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "HTTP", "Json" });
Storage
A small JSON file in the per-user settings folder keeps the key, the instance id and the latest token. It is the buyer’s own key on the buyer’s own machine, and the token is signed, so plain text is a fair trade. I found no cross-platform keychain call in Unreal’s core modules; use the platform’s own API if you want one.
// ClavemStorage.h
#pragma once
#include "CoreMinimal.h"
#include "Dom/JsonObject.h"
#include "HAL/FileManager.h"
#include "HAL/PlatformProcess.h"
#include "Misc/FileHelper.h"
#include "Misc/Paths.h"
#include "Serialization/JsonSerializer.h"
struct FClavemSaved { FString Key, InstanceId, Token; };
inline FString ClavemFile()
{
// UserSettingsDir() returns a shared buffer: copy it into an FString at once.
return FPaths::Combine(FString(FPlatformProcess::UserSettingsDir()), TEXT("Inkwell"), TEXT("license.json"));
}
inline bool LoadSaved(FClavemSaved& Out)
{
FString Text;
TSharedPtr<FJsonObject> Json;
if (!FFileHelper::LoadFileToString(Text, *ClavemFile())
|| !FJsonSerializer::Deserialize(TJsonReaderFactory<>::Create(Text), Json) || !Json.IsValid())
{
return false;
}
return Json->TryGetStringField(TEXT("key"), Out.Key) && Json->TryGetStringField(TEXT("instance_id"), Out.InstanceId)
&& Json->TryGetStringField(TEXT("token"), Out.Token);
}
inline void SaveSaved(const FClavemSaved& In)
{
TSharedRef<FJsonObject> Json = MakeShared<FJsonObject>();
Json->SetStringField(TEXT("key"), In.Key);
Json->SetStringField(TEXT("instance_id"), In.InstanceId);
Json->SetStringField(TEXT("token"), In.Token);
FString Text;
FJsonSerializer::Serialize(Json, TJsonWriterFactory<>::Create(&Text));
IFileManager::Get().MakeDirectory(*FPaths::GetPath(ClavemFile()), true);
FFileHelper::SaveStringToFile(Text, *ClavemFile());
}
inline void ClearSaved() { IFileManager::Get().Delete(*ClavemFile()); }
The subsystem
// ClavemLicenseSubsystem.cpp (the header declares Initialize, Validate, GetState and OnStateChanged)
void UClavemLicenseSubsystem::Initialize(FSubsystemCollectionBase& Collection)
{
Super::Initialize(Collection);
Validate();
}
void UClavemLicenseSubsystem::Validate()
{
FClavemSaved Saved;
if (!LoadSaved(Saved)) { SetState(EClavemState::Unlicensed); return; }
TSharedRef<FJsonObject> Body = MakeShared<FJsonObject>();
Body->SetStringField(TEXT("license_key"), Saved.Key);
Body->SetStringField(TEXT("instance_id"), Saved.InstanceId);
FString Payload;
FJsonSerializer::Serialize(Body, TJsonWriterFactory<>::Create(&Payload));
TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = FHttpModule::Get().CreateRequest();
Request->SetURL(TEXT("https://clavem.io/v1/licenses/validate"));
Request->SetVerb(TEXT("POST"));
Request->SetHeader(TEXT("Content-Type"), TEXT("application/json"));
Request->SetContentAsString(Payload);
Request->SetTimeout(8.f);
Request->OnProcessRequestComplete().BindUObject(this, &UClavemLicenseSubsystem::OnResponse);
Request->ProcessRequest();
}
void UClavemLicenseSubsystem::OnResponse(FHttpRequestPtr, FHttpResponsePtr Response, bool bConnected)
{
// bConnected only says a response arrived. Response is null when none did.
const int32 Status = (bConnected && Response.IsValid()) ? Response->GetResponseCode() : 0;
TSharedPtr<FJsonObject> Json;
if (Status > 0) { FJsonSerializer::Deserialize(TJsonReaderFactory<>::Create(Response->GetContentAsString()), Json); }
FString Error;
if (Json.IsValid()) { Json->TryGetStringField(TEXT("error"), Error); }
FClavemSaved Saved;
if (!LoadSaved(Saved)) { SetState(EClavemState::Unlicensed); return; }
if (Status == 200 && Json.IsValid())
{
// Keep the new token even when the license is not valid: offline, it then says so.
if (Json->TryGetStringField(TEXT("token"), Saved.Token)) { SaveSaved(Saved); }
bool bValid = false;
Json->TryGetBoolField(TEXT("valid"), bValid);
SetState(bValid ? EClavemState::Licensed : EClavemState::Invalid, Error);
}
else if (Status == 404)
{
ClearSaved(); // unknown key, or this device was removed: ask for the key again
SetState(EClavemState::Invalid, Error);
}
else
{
// No response, 400, 429 or 503: trust the stored token while it is fresh.
const int64 Now = FDateTime::UtcNow().ToUnixTimestamp();
const bool bFresh = Clavem::IsLicensed(Clavem::VerifyToken(Saved.Token, Clavem::PublicKey), Clavem::ProductId, Now);
SetState(bFresh ? EClavemState::Licensed : EClavemState::NeedsNetwork);
}
}
SetState stores the enum and calls OnStateChanged.Broadcast(State, Message), a BlueprintAssignable delegate, so a menu widget can react without C++.
What each outcome means
| Outcome | How it arrives | What to do |
|---|---|---|
| No answer | bConnected false or null Response |
Verify the stored token |
200, valid: true |
Status 200 | Store the new token, licensed |
200, valid: false |
error holds the sentence |
Store the token, show the message, keep the key: a renewal can revive it |
| 404 | license_key not found. or instance_id not found. |
Clear storage, ask for the key |
| 400 | A bug in your request, such as an empty key | Log it, use the stored token |
| 429 | Retry-After: 60 |
Use the stored token, try again later |
| 503 | Retry-After: 5 |
Use the stored token, try again later |
Unreal details that cause trouble
- Set your own timeout. Without
SetTimeout, the request usesFHttpModule::GetTimeout(), a project-wide value you may have raised for large downloads. - Do not start from a constructor or a CDO. The editor and the cooker create default objects, so a network call there runs every time someone opens the project. A game-instance subsystem exists only in a running game.
- Never wait for the request. Blocking the game thread on an HTTP request freezes rendering. Show the state from the delegate instead.
- Delegate lifetime.
BindUObjectstops firing once the subsystem is destroyed, for example when Play In Editor ends. A raw lambda capturingthisdoes not; useBindWeakLambda. - Dedicated servers have no buyer to ask for a key. Decide separately whether servers need a license. Left alone, the subsystem sits in
Unlicensedthere.
Rate limits in a game
The License API allows 120 requests per minute per IP address and 60 per minute per key. Validate once per launch, not per level load. A LAN event where 200 machines start the game within one minute behind one address pushes about 80 of them past the IP limit. They get a 429 with Retry-After: 60 and keep playing on the stored token, which stays good for 14 days after its last refresh. That is the reason the 429 branch uses the token instead of an error screen.
Doing this with Clavem
Clavem’s License API takes these three calls with no authentication. The product id and public key come from your product page, and the request fields are in the API reference. Nothing here needs an SDK.
Questions
Does bWasSuccessful mean the license is valid?
No. In the HTTP module it means a response arrived. A 404 or 429 still reports true, so read GetResponseCode() and the JSON body. The Response pointer is null when nothing arrived.
Which thread runs the completion delegate?
By default the HTTP module completes requests on the game thread, so touching UObjects and broadcasting Blueprint delegates is safe. IHttpRequest has SetDelegateThreadPolicy if you change that.