Unreal SDK

Refer to the Installation section for installation information.

The SDK is an engine plugin. Its entry point is UGamebeastSubsystem, a game instance subsystem, so there is one SDK per game instance (and one per Play In Editor session). Every method is available from C++ and from Blueprint.

Calling into Gamebeast from UnrealCopy Anchor Link

#include "GamebeastSubsystem.h"

void UMyGameInstance::Init()
{
    Super::Init();

    FGamebeastSetupOptions Options;
    Options.ApiKey = TEXT("abcd-efgh-1234-5678");
    Options.Configurations = { TEXT("MyConfig") };
    GetSubsystem<UGamebeastSubsystem>()->SetupWithOptions(Options);
}

Anywhere else, get the subsystem from any object with a world:

UGamebeastSubsystem* Gamebeast = UGamebeastSubsystem::Get(this);

In Blueprint, use the Gamebeast Subsystem node.

The SDK can also start itself from Project Settings, with no setup code. See Automatic initialization below.

Subsystem methodsCopy Anchor Link

Setup(ApiKey)Copy Anchor Link

→boolreturn type

Starts the SDK with an SDK Key and the rest of the values from Project Settings. Returns false if the SDK is already running (call Shutdown first) or the key is empty. Before Setup, services log a warning and do nothing.

UsageCopy Anchor Link

UGamebeastSubsystem::Get(this)->Setup(TEXT("abcd-efgh-1234-5678"));

SetupWithOptions(Options)Copy Anchor Link

→boolreturn type

Starts the SDK with explicit options.

TypesCopy Anchor Link

USTRUCT(BlueprintType)
struct FGamebeastSetupOptions
{
    // Your project's SDK Key. Required.
    FString ApiKey;

    // Optional id for the local player. When empty, the SDK generates an anonymous id on
    // first launch and saves it on the device, so the same player is reported across sessions.
    FString DistinctId;

    // Optional: "production" or "development". Leave empty to choose automatically:
    // development in the editor (including Play In Editor), production in packaged builds.
    FString Environment;

    // Optional: configurations to load at startup, by alias. They gate IsReady/OnReady.
    TArray<FString> Configurations;

    // Optional targeting properties for experiments: strings, numbers, booleans,
    // or arrays of one of those.
    FGamebeastProperties UserProperties;

    // How often the SDK talks to Gamebeast. See Rates below.
    FGamebeastRates Rates;

    // In the editor (including Play In Editor), use each rate's minimum so changes show up
    // quickly. Packaged builds always use Rates.
    bool bFastRatesInEditor = true;

    // Start a new session after this many seconds in the background. 0 keeps one per run.
    float SessionTimeoutSeconds = 1800.f;

    // Verbose LogGamebeast output.
    bool bDebugLogging = false;

    // Override the Gamebeast API base URL. Leave as-is.
    FString ApiUrl = TEXT("https://api.gamebeast.gg");
};

UsageCopy Anchor Link

FGamebeastSetupOptions Options;
Options.ApiKey = TEXT("abcd-efgh-1234-5678");
Options.DistinctId = TEXT("player-123");
Options.Configurations = { TEXT("MyConfig") };
Options.UserProperties = FGamebeastProperties().Set(TEXT("vip"), true);

UGamebeastSubsystem::Get(this)->SetupWithOptions(Options);

Identify(DistinctId)Copy Anchor Link

→voidreturn type

Switches the local player's distinct id, for example after a login. Configurations are re-evaluated for the new player right away, and experiment assignments update with them. Markers recorded before the switch keep the id they were recorded under.

The id is not saved. Call Identify again on the next launch once your login state is restored, or pass it in FGamebeastSetupOptions::DistinctId.

UsageCopy Anchor Link

UGamebeastSubsystem::Get(this)->Identify(TEXT("player-123"));

ResetIdentity()Copy Anchor Link

→voidreturn type

Goes back to the device's anonymous distinct id, for example after a logout.

UpdateRates(Rates)Copy Anchor Link

→voidreturn type

Changes the rates while the game runs. Values below a minimum are raised to it with a warning. Rates set this way also apply in the editor, overriding bFastRatesInEditor for the rest of the session. GetRates() returns the rates in effect.

UsageCopy Anchor Link

FGamebeastRates Rates;
Rates.StatusPollRate = 120.f;
UGamebeastSubsystem::Get(this)->UpdateRates(Rates);

Shutdown()Copy Anchor Link

→voidreturn type

Saves buffered markers to the device (they're sent on the next launch) and stops the SDK. Setup may be called again afterwards. The subsystem shuts down by itself when the game instance ends, so you rarely need this.

GetMarkers(), GetConfigs(), GetExperiments(), GetCohorts()Copy Anchor Link

→UGamebeastMarkers* / UGamebeastConfigs* / UGamebeastExperiments* / UGamebeastCohorts*return type

The services. They are never null, even before Setup.

GetDistinctId(), GetSessionId(), GetEnvironment(), IsInitialized()Copy Anchor Link

The effective distinct id (the one supplied, or the anonymous one), the current session id, the environment alias the SDK reports to (production, development, or a custom alias), and whether Setup has run. The strings are empty before Setup.

Automatic initializationCopy Anchor Link

Instead of calling Setup, let the SDK start itself:

1. Open Edit > Project Settings > Plugins > Gamebeast.
2. Paste your SDK Key into Api Key, and set any other options.

The SDK starts on the first frame of each game instance. A Setup call in your GameInstance's Init runs before that, so it takes precedence. DistinctId and UserProperties aren't in Project Settings: use SetupWithOptions or Identify for those.

Dedicated servers don't start automatically, since a server has no local player. Turn on Auto Initialize On Dedicated Server if you want that, or call Setup on the server yourself.

RatesCopy Anchor Link

How often the SDK talks to Gamebeast, in seconds. Set them under Rates in Project Settings, in FGamebeastSetupOptions::Rates, or at runtime with UpdateRates.

A value below its minimum is raised to the minimum, with a warning in the log.

EnvironmentsCopy Anchor Link

One setting, Environment, picks where the SDK reports. Leave it empty and the SDK chooses; set it to "production" or "development" and that environment is used in the editor and in packaged builds alike.

Any other value logs a warning and is treated as empty.

Saved dataCopy Anchor Link

The SDK keeps a few files under Saved/Gamebeast/ in the project (or the platform's saved-data folder in packaged builds): the anonymous player id, a cache of each configuration, and markers waiting to be sent. Delete the folder to start over as a new player.