Analytics and Events

Your game reports to Flock over two separate surfaces. They answer different questions, are read by different people, and appear on different dashboards. Picking the wrong one puts your data somewhere real but useless — so it is worth two minutes up front.

Scope: events and analytics are aggregated per game.

	Analytics	Log events
Answers	What did players do?	What went wrong?
Read by	Design, product, LiveOps	Engineering
Covers	Sessions, screen views, transactions	Debug entries, logic errors, exceptions
Where to read it	Dashboards → Game Metrics	Diagnostics → Events and Diagnostics → Errors

A crash is not a funnel step. Sending one through the other surface does not fail and does not warn — the entry is accepted, stored, and shown on a dashboard nobody was looking at.

Analytics

Engagement, retention and monetization, built from the sessions, screen views and transactions your game reports. Read on Dashboards → Game Metrics. How each number is counted is in Metric Definitions.

Dashboard
Unity
Unreal

Analytics dashboards — Engagement, retention, and monetization dashboards in Flock.

Sessions start and end automatically around sign-in. Screen views tell you where players spend their time, and purchases made through Flock report their own transactions with no call from you. Gameplay events — a level completed, an item viewed — go through TrackEvent, never through a log entry. The examples run inside an async method; receiptId stands for your own store’s receipt.

using System.Collections.Generic;
using Flock;
using Flock.Analytics;

FlockClient.Instance.Analytics.RecordScreenView("shop");

// A gameplay event, with properties the dashboards can chart. False when it was refused
// (no consent, an empty or reserved name); the Console says why.
bool tracked = FlockClient.Instance.Analytics.TrackEvent("level_complete",
    new Dictionary<string, object> { { "level", 3 }, { "flawless", true } }, "progression");

// A purchase Flock did not make (your own store, for example): record its transaction yourself.
await FlockClient.Instance.Analytics.RecordTransactionAsync(4.99, "USD",
    paymentProvider: "my_store", externalTransactionId: receiptId);

// Optional: await delivery of everything queued (before a critical moment).
// The result counts what was sent and what the server refused for good.
FlockFlushResult flushed = await FlockClient.Instance.Analytics.FlushAsync();

Events are written to disk and delivered while a player is signed in. Never record a purchase made through Flock’s shop yourself: it is reported already, and would count twice. Everything here is off when Analytics Enabled (Advanced Settings tab) is unticked.Asking for consent. To ask the player before tracking, tick Analytics Require Explicit Consent (Advanced Settings tab, Analytics Settings): nothing is tracked until your game records the answer. The answer is kept across launches.

using Flock;

// From your consent screen's buttons.
FlockClient.Instance.Analytics.SetConsent(true);    // Agreed: tracking starts.
FlockClient.Instance.Analytics.SetConsent(false);   // Declined or withdrawn: tracking stops.

bool tracking = FlockClient.Instance.Analytics.HasConsent;

Withdrawing consent does not delete what is still queued on the device; EraseLocalAnalyticsData() does. Transactions are recorded either way, as they are kept for the purchase itself.

The Flock | Analytics nodes need no Target pin and are safe no-ops before the SDK initializes. Sessions start and end automatically around sign-in, and purchases report their own transactions. Gameplay events — a level completed, an item viewed — go through Flock Track Event (TrackAnalyticsEvent), never through a log entry, which lives in the Flock | Diagnostics drawer.Build an event’s properties with Make Flock Event Properties and the Flock Event Property nodes ((Integer), (Float), (String), (Boolean), (String Array)), which keep a number a number so the dashboards can chart it.

A Level Completed custom event, Make Flock Event Properties, Flock Event Property (Integer) with stars set to 3, then Flock Track Event named level_completed with those properties — Track a gameplay event with a number property the dashboards can chart.

#include "FlockSubsystem.h"

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);   // this: any object in the game's world

Sdk->RecordAnalyticsScreenView(TEXT("shop"));
Sdk->TrackAnalyticsEvent(TEXT("level_complete"),
    FFlockCommandData().Set(TEXT("level"), 3).Set(TEXT("flawless"), true), TEXT("progression"));

Events are written to disk and delivered while a player is signed in; one recorded before anyone signs in is credited to whoever signs in next. Everything here is off when Analytics Enabled is unticked.

Sessions

A session is the unit everything else is attributed to, and the SDK manages its whole life for you.


Starts	on sign-in, not at startup — a session belongs to a player, so there is nobody to attribute one to before then
Ends	on sign-out, on quit, and on timeout
Backgrounding	does not end a session — it pauses it, and time spent backgrounded is not counted as playtime
Timeout	a player who comes back after being away longer than the session-timeout setting (30 seconds by default) gets a new session; the old one is closed

That last row is the one worth knowing. Without it, a player who backgrounds your game overnight and returns in the morning reports a single fourteen-hour session, and every average you build on top of that is wrong.

Sessions are per sign-in, so a shared device reports one session per player rather than one per launch. Signing out closes the session before the next player starts theirs.

Withdrawing analytics consent discards the session in progress rather than sending it. Objecting to further processing is not a request to transmit one last record.

Log events

Developer diagnostics, in exactly three categories. Which one you pick decides where the entry appears.

Category	Appears on	Use for
Debug	Diagnostics → Events	Trace and context — things that are not faults
Error	Diagnostics → Errors	Something wrong that did not raise
Exception	Diagnostics → Errors	A caught failure, with its stack trace

These are for diagnostics, not gameplay. A level-complete recorded as a debug entry lands in Diagnostics → Events, where nobody building a retention chart will find it — and it will not appear in Game Metrics at all.

Unity
Unreal

Log calls are synchronous and never block gameplay: they enqueue to an on-disk buffer and the SDK batches and delivers them for you. Exceptions nobody catches are captured for you (Analytics Capture Exceptions, Advanced Settings tab, Exceptions). LoadSaveFile stands for your own code.

using System;
using System.Collections.Generic;
using Flock;

// Debug: Diagnostics → Events
FlockClient.Instance.Analytics.LogDiagnosticEvent("matchmaking started",
    new Dictionary<string, object> { { "queue", "ranked" } });

// Error: something wrong that did not raise, with your own code and the check that failed
FlockClient.Instance.Analytics.LogDiagnosticError("quest ended with no reward",
    logicalExpression: "rewards.Count > 0", errorCode: "QUEST_NO_REWARD",
    errorData: new Dictionary<string, object> { { "quest", "q_17" } });

// Exception: a failure you caught
try
{
    LoadSaveFile();
}
catch (Exception ex)
{
    FlockClient.Instance.Analytics.LogDiagnosticException(ex);
}

These were called LogEvent, LogError and LogException before; the old names still compile, with a warning naming the new ones.

A Level Loaded custom event wired into Flock Log Diagnostic Event with the Message Loaded the forest level — Log a diagnostic entry: its Message, and Extra Data built with the Flock Metadata nodes when it needs any.

#include "FlockSubsystem.h"
#include "Analytics/FlockMetadata.h"

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);   // this: any object in the game's world

Sdk->LogDiagnosticEvent(TEXT("matchmaking started"),
    FFlockMetadata().Add(TEXT("queue"), TEXT("ranked")));

FFlockLogDetails Details;
Details.ErrorCode = TEXT("QUEST_NO_REWARD");                // your own code for this fault
Details.LogicalExpression = TEXT("Rewards.Num() > 0");     // the check that failed
Details.ErrorData = FFlockMetadata().Add(TEXT("quest"), TEXT("q_17")).Values;   // what was wrong
Sdk->LogDiagnosticError(TEXT("quest ended with no reward"), Details);

FFlockLogDetails describes an error or exception: ErrorCode and LogicalExpression (your own code and the check that failed), ErrorData (what was wrong) and ExtraData (where the player was).Logging returns immediately: entries are written to disk and delivered later, so a call is cheap and nothing is lost to a crash or a dead network. A run that dies without a clean quit is reported on the next launch.These nodes live under Flock | Diagnostics, apart from the analytics ones, and their Extra Data is a map of strings built with the Flock Metadata nodes. They were called Flock Log Event, Error and Exception (LogAnalyticsEvent and friends) before SDK 1.21.0; the old names still work and the editor points at the new ones.

Unexpected-termination detection

If a play session ends without a clean quit — a crash, a hang the player force-killed, or the OS evicting the game — the SDK detects it on the next launch and reports one app_termination event automatically. No integration needed.

Property	Meaning
`classification`	`background_kill` (killed while backgrounded — normal on mobile) or `abnormal` (died in the foreground without quitting)
`previous_session_id`	The session that died
`last_alive_at`	Approximate time of death
`unhandled_exception_count`	Exceptions seen that run — context, not proof of a crash

Watch the abnormal rate per game version — a jump after a release is your earliest stability signal, no crash reporter required. Closing the game normally (in-game quit, Alt-F4, swiping the app away) never counts as abnormal.

Name things consistently. Whichever surface you are on, a small vocabulary of well-chosen names makes a dashboard readable and a sprawling one makes it useless.

Getting Started

Concepts

Features

Reference

Analytics and Events

Analytics

Sessions

Log events

Unexpected-termination detection

​Analytics

​Sessions

​Log events

​Unexpected-termination detection

Analytics

Sessions

Log events

Unexpected-termination detection