Download the Unity SDK
.unitypackage from the releases page.Requirements
- Unity 2021.3 or newer
com.unity.nuget.newtonsoft-json3.0.2+
Setup
Import the package
.unitypackage (Assets → Import Package → Custom Package). Keep everything ticked: the SDK lands
in Assets/FlockSDK/, its samples in Assets/FlockSDK/Samples/.Add the JSON dependency
Packages/manifest.json and add this line inside its "dependencies" block, beside the lines
already there (do not replace the file):com.unity.nuget.newtonsoft-json.Configure
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 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.
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.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.).- Automatic (default)
- Scene component
- Manual
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.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 aFlock namespace. Add the using lines a script needs:
.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 separateRegisterWith…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.
- Device
- Email
- Google / Apple / Steam / Facebook / Discord
async method: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).

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).
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.

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.
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, 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 raisesFlockException. 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.
Reading the parts yourself
If you’d rather build your own text, every piece is on the exception: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).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.
