Analytics

Inherits: Object

Opt-in analytics singleton for editor demographics and game session events.

Description

Analytics queues JSON events and optionally POSTs them to an ingest endpoint. Editor builds compiled with editor_analytics=yes record demographic/usage events after consent. Export templates compiled with analytics=yes expose a small game SDK (track(), session start/end).

Editor get_app_id(), get_build_id(), and ingest URL are baked at compile time (editor_app_id, editor_build_id, editor_analytics_endpoint) and cannot be changed from CLI, environment, or Editor Settings. If editor_app_id is omitted, the editor uses custom_blazium_engine. If editor_build_id is omitted, the editor uses the engine git hash. An empty editor ingest URL disables collection and sending (no queue growth). Export templates may optionally bake template_app_id, template_build_id, and template_analytics_endpoint; a non-empty bake locks that field. An empty template analytics URL still means "use Project Settings", not "disable". Consent priority is CLI --analytics=, then BLAZIUM_ANALYTICS_CONSENT, then Editor Settings or set_consent(). Anonymous mode (default) omits device_uid; identified mode sends OS.get_unique_id(). See get_resolved_config().

Methods

void	flush()
String	get_app_id() const
String	get_app_version() const
String	get_build_channel() const
String	get_build_id() const
String	get_consent() const
String	get_device_uid() const
int	get_queue_size() const
Dictionary	get_resolved_config() const
void	identify(user_id: String)
bool	is_anonymous() const
bool	is_available() const
bool	is_enabled() const
void	set_anonymous(anonymous: bool)
void	set_consent(accepted: bool)
void	set_user_properties(properties: Dictionary)
void	track(event: String, properties: Dictionary = {})

---

Signals

flush_failed(message: String) 🔗

Emitted when flush() cannot POST queued events.

---

flush_succeeded(count: int) 🔗

Emitted after a successful flush. count is the number of events sent.

---

Enumerations

enum Consent: 🔗

Consent CONSENT_UNSET = 0

Consent has not been set.

Consent CONSENT_ACCEPTED = 1

Analytics sending is allowed.

Consent CONSENT_DECLINED = 2

Analytics sending is declined.

---

Method Descriptions

void flush() 🔗

POSTs queued events to the resolved endpoint. Emits flush_succeeded or flush_failed. An empty endpoint leaves the queue on disk and logs that the flush was dropped.

---

String get_app_id() const 🔗

Returns the product id sent on every event and as X-App-Id on flush. In the editor this is the SCons-baked value. In exported games a non-empty template_app_id bake wins and is locked; otherwise Project Settings are used. Shared with CrashReporter.get_app_id(). There is no engine CLI override.

---

String get_app_version() const 🔗

Returns the resolved product version sent on every event.

---

String get_build_channel() const 🔗

Returns the resolved build channel (dev, beta, release, or custom).

---

String get_build_id() const 🔗

Returns the build id sent on every event and as X-Build-Id on flush. In the editor this is the SCons-baked value. In exported games a non-empty template_build_id bake wins and is locked; otherwise Project Settings are used. Shared with CrashReporter.get_build_id(). There is no engine CLI override.

---

String get_consent() const 🔗

Returns unset, accepted, or declined after CLI, environment, and persisted settings.

---

String get_device_uid() const 🔗

Returns OS.get_unique_id() when identified, or an empty string when anonymous.

---

int get_queue_size() const 🔗

Returns the number of events waiting in the on-disk JSONL queue.

---

Dictionary get_resolved_config() const 🔗

Returns identity, consent, endpoint, and queue path. Editor identity and ingest URL are compile-time only; an empty editor URL disables collection. Game fields are locked when the matching template_* bake is non-empty; otherwise they come from Project Settings.

---

void identify(user_id: String) 🔗

Stores a game user id attached to later events. No-op in anonymous mode.

---

bool is_anonymous() const 🔗

Returns true when events omit device_uid.

---

bool is_available() const 🔗

Returns true when the Analytics module is compiled in.

---

bool is_enabled() const 🔗

Returns true when events may be queued (feature flag plus consent).

---

void set_anonymous(anonymous: bool) 🔗

Sets anonymous mode for this process. New events omit or include device_uid accordingly; already queued events keep the mode they were created with.

---

void set_consent(accepted: bool) 🔗

Accepts or declines analytics. Editor builds persist this in Editor Settings.

---

void set_user_properties(properties: Dictionary) 🔗

Merges game user properties into later events. No-op in anonymous mode.

---

void track(event: String, properties: Dictionary = {}) 🔗

Queues event with properties plus automatic runtime context. Editor and game contexts use separate property sets.