Skip to main content
The Flock Unity SDK connects your game to the Flock backend: player auth, save data, economy, remote config, downloadable assets, and analytics — configured from one in-editor window, with strongly typed C# generated from your own schemas.

Download the Unity SDK

Get the latest .unitypackage from the releases page.

Requirements

  • Unity 2021.3 or newer
  • com.unity.nuget.newtonsoft-json 3.0.2+

Setup

1

Import the package

Download the latest release and import the .unitypackage (Assets → Import Package → Custom Package). Keep everything ticked: the SDK lands in Assets/FlockSDK/, its samples in Assets/FlockSDK/Samples/.
2

Add the JSON dependency

Open Packages/manifest.json and add this line inside its "dependencies" block, beside the lines already there (do not replace the file):
Or add it from the Package Manager: + → Add package by name, then com.unity.nuget.newtonsoft-json.
3

Configure

Open Flock → Settings. On the Configuration tab, fill in the API Credentials card from your game’s page on the dashboard:Values are saved to Assets/Resources/FlockConfig.asset. One thing must happen before the SDK can start:
  • Resolve Game Version — your version name is looked up and its ID is baked into the config: written into the config asset in the editor, so every build carries it (the read-only Resolved Version ID field). Runtime init uses that baked ID directly and never calls the server, so it must resolve before you play or build. The window resolves it automatically when your credentials change; the Resolve Game Version button does it again.
The Setup card at the top of the tab also has a Verify button on its Connection row. It is an optional check that your Api Url and Api Key reach Flock; the SDK starts without it.
Flock Settings window, Configuration tab, with the Setup card and the API Credentials card

The Configuration tab: the Setup card (the Scene bootstrap row reads "Not needed — Auto-Initialize On Load is on.") and the API Credentials card with Api Url, Api Key, Game Name, Game Version and the Resolved Version ID filled in.

The API Key ships inside your build (it’s loaded from Resources at runtime). Use a key scoped to the right environment, and rotate it on the dashboard if it leaks.

Your first call

With Auto-Initialize On Load on (the default), the SDK is already running when your first scene loads, and it restores a player’s saved sign-in in the background. Add this component to a GameObject in your first scene: it waits for that restore, signs the player in only when nobody is signed in, then makes a call.
Success is Signed in as and the player’s ID in the Console. With no id passed, the device calls use Authentication.ThisDeviceId: an id the SDK makes the first time it is needed and keeps in the game’s saved files (Flock/device_id.txt under Application.persistentDataPath; the browser’s storage on WebGL), the same kind on every platform. Signing out keeps it. A new one comes after a reinstall, clearing the app’s data or deleting the file, and on WebGL after clearing the site’s data, in a private window, or when the game is served from another page address; restoring a phone from a backup can bring the old one back. With a new id comes a new player, so offer account linking (an email or a platform account) to players who want to get back in on another device. Pass an id of your own only in two cases; it is sent as it is. An empty string is not the same as leaving the id out: the sign-in and registration calls send it and the server refuses it, and LinkDeviceAsync refuses it before sending.
  • Your game already signs players in with its own id (SystemInfo.deviceUniqueIdentifier, or an id kept in PlayerPrefs): keep passing that id. Leaving it out would give every existing player a new, empty account.
  • Two copies of the game on one computer (the Editor and a build) share the kept id, and so are one player: pass a different id in one of them.

Initialization

The SDK can start three ways. Automatic is the default and fits most games; the other two trade a little setup for control over when init runs (after a splash screen, EULA, etc.).
Nothing to call — the SDK initializes from FlockConfig.asset before the first scene loads and restores a saved session in the background. React to lifecycle events if you need to. Only OnInitialized and OnInitializationFailed run again for a handler added late: the restore can finish before your script subscribes, so read FlockClient.IsRestoringSession too.
Init is fail-fast. A bad config throws (the auto-init path logs instead of crashing), and FlockClient.Instance throws until init succeeds. Guard with FlockClient.IsInitialized, inspect FlockClient.InitializationError, or handle FlockEvents.OnInitializationFailed.

Usings and assembly definitions

Every SDK type is in a Flock namespace. Add the using lines a script needs: A script in your game’s default assembly (no assembly definition of its own) sees the SDK as is. A script under an assembly definition (.asmdef) of your own needs a reference to Flock.Runtime in that assembly definition’s Assembly Definition References. Code that Sync Schemas writes goes to Assets/Flock/Generated/, which has no assembly definition, so it is part of the default assembly: a script under an assembly definition of your own cannot use the generated names. Call them from a script outside it, or the raw calls that take a name (UnlockAchievementAsync("first_win")).

Authenticate a player

Signing in does not create an account — registering is a separate RegisterWith…Async call, and a register that creates the account also signs the player in. Registering an identity that already has an account succeeds rather than failing (it returns null and signs nobody in), so you can send the player to a login instead. Auth methods throw on failure, so wrap them in try/catch.
Log in, and register on the first launch, as Your first call shows. The code runs inside an async method:
Sessions refresh automatically. Subscribe to FlockEvents.OnAuthenticated and OnAuthExpired to drive your UI:

Work with your game data

Open the Code Generation tab of Flock → Settings and click Sync Schemas (in its Actions card) to turn your dashboard’s player templates, configs and shops into typed C# accessors under the Generated Code Path (Assets/Flock/Generated/ by default, set in the Output Folder card).
Code Generation tab in the Flock window

The Code Generation tab: the Status card after a sync, then How It Works, Output Folder (Generated Code Path) and Actions (Sync Schemas, Delete Generated Code, Open Catalog).

The example below assumes a player template named PlayerProgress (fields level, xp, class), a game config named Gameplay (max_lives, spawn_rate, welcome_text) and a shop item GemPack on your dashboard. They are examples: create them on the dashboard first (Player Data, Remote Config, Shops and Inventory), or use your own names. The code runs inside an async method.
These accessors don’t exist until you sync. GetPlayerProgressAsync above is generated from a PlayerProgress template on your dashboard. Write the call before the template exists — or before the first Sync Schemas — and it fails to compile, not at runtime. The using Flock.Generated… lines fail the same way until the first sync, since those namespaces are written by it:
That error has two causes. Either the script lacks the using line for the generated namespace (using Flock.Generated.Templates; here — see Usings and assembly definitions), or the accessor was never generated. The order is always: author the schema on the dashboard → Sync Schemas → write the call. Adding or renaming a template later means syncing again.Unity’s own compiler error can’t tell you any of that, so the SDK watches compilation and prints the missing step in the Console when it recognises one of these. The Status card of the Code Generation tab also shows whether a sync has ever run, and which game version it last synced for.
Each sync also writes a read-only FlockContentCatalog asset (Open Catalog in the Actions card) — designers can browse every shop, config, and template in the Inspector without touching code or the dashboard.
FlockContentCatalog asset open in the Inspector

The generated FlockContentCatalog — shops, configs, and templates with their values.

Samples

The .unitypackage brings three samples under Assets/FlockSDK/Samples/, each one script you add to an empty GameObject before pressing Play:
  • QuickStart (FlockQuickStartSample) — log in with this device, see the player, send a test analytics event, read the player’s data.
  • Shop (FlockShopSample) — sign in, list the shops’ items, buy with the wallet or real money, restore purchases. See Shops & inventory.
  • Multiplayer (FlockPlayWithFriendsSample, FlockQuickMatchSample) — host and join by code, or find a match in a queue. They compile only with Netcode for GameObjects installed; see Multiplayer.
Each folder’s README.md has its steps.

Explore features

Players & auth

Account linking

Player data

Shops & inventory

Leaderboards

Notifications

Remote config

Assets

Analytics & events

Multiplayer

Playtesting with Protokite

Advanced settings

The Advanced Settings tab tunes debug logs, analytics (with exception capture and the event cache), the asset cache, the offline cache (Enable Offline Cache and Offline Cache Directory: copies of what the SDK’s read calls returned, kept on disk and served when the network is not there), HTTP retries, multiplayer’s party refresh, and editor tools (including Auto-Initialize On Load). The defaults are sensible — change them only when you need to.
Advanced Settings tab in the Flock window

Advanced Settings, top to bottom: Optional, Analytics (with Exceptions and Caching), Asset Cache, Offline Cache, HTTP Retry Policy, Multiplayer and Tools.

Platform notes

WebGL: a browser build cannot write files the way the SDK’s caches do. Before you build for WebGL, untick Enable Asset Cache (Asset Cache card) and Enable Offline Cache (Offline Cache card) on the Advanced Settings tab. Assets then download each time they are asked for, and reads need the network.

Error handling

Every SDK failure raises FlockException. Its Message names the call that failed, the server’s own reason, the coded identifier, the HTTP status — and a Fix: line telling you what to do next. The examples below run inside an async method.
Console
The same server code can mean different things depending on how the player signed in, so the fix is specific to the credential — the message above says “register this device”, while the identical code on an email sign-in says the password was wrong.

Reading the parts yourself

If you’d rather build your own text, every piece is on the exception:
Branch on ErrorCode, never on message text. Codes are a stable contract; wording is not and will change between versions.
FlockShopItemId.Sword is generated by Sync Schemas for a shop item named Sword (see Work with your game data); use your own item.
Hint is written for you, not your players — it names SDK methods and dashboard steps. Show it in your own debug overlay or logs, and write separate player-facing copy for your UI. You can pull the same text for any code with FlockErrorHints.For(errorCode).
A failure with no StatusCode got no refusal from the server: the request never reached it (a connectivity problem on the device, which Hint says), or the SDK refused the call itself, before sending it (an empty argument, nobody signed in), and Message names what to change.
The full API reference, codegen details, offline cache, and analytics tuning live in the SDK README.