GFAnalyticsUtility

API Reference / Standard / 类索引

• 路径：addons/gf/standard/utilities/analytics/gf_analytics_utility.gd
• 模块：Standard
• 继承：GFUtility
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：3.17.0

通用事件分析与批量上报工具。 负责事件排队、环境上下文采集、批量 flush 与失败重排。 endpoint 为空时不会访问网络，可作为本地事件汇聚或测试通道使用。

成员概览

类型	名称	签名
信号	event_tracked	signal event_tracked(event_name: StringName, event_data: Dictionary)
信号	flush_started	signal flush_started(batch: Array)
信号	flush_completed	signal flush_completed(result: Dictionary)
信号	flush_failed	signal flush_failed(result: Dictionary)
属性	config	var config: GFAnalyticsConfig = GFAnalyticsConfig.new()
属性	payload_builder	var payload_builder: Callable = Callable()
属性	transport_callback	var transport_callback: Callable = Callable()
属性	response_parser	var response_parser: Callable = Callable()
方法	init	func init() -> void:
方法	dispose	func dispose() -> void:
方法	tick	func tick(delta: float) -> void:
方法	configure	func configure(analytics_config: GFAnalyticsConfig) -> void:
方法	identify	func identify(client_id: String) -> void:
方法	track	func track(event_name: StringName, properties: Dictionary = {}) -> void:
方法	flush	func flush() -> void:
方法	shutdown	func shutdown(flush_remaining: bool = true) -> void:
方法	get_queue_size	func get_queue_size() -> int:
方法	get_session_id	func get_session_id() -> String:
方法	get_client_id	func get_client_id() -> String:
方法	clear_queue	func clear_queue() -> void:
方法	capture_context	func capture_context() -> Dictionary:

信号

event_tracked

• API：public

signal event_tracked(event_name: StringName, event_data: Dictionary)

事件进入队列时发出。

参数：

名称	说明
event_name	事件名。
event_data	已入队事件数据。

结构：

• event_data: Dictionary with event, client_id, session_id, timestamp, properties, and optional context.

flush_started

• API：public

signal flush_started(batch: Array)

开始 flush 时发出。

参数：

名称	说明
batch	本次 flush 的事件批次。

结构：

• batch: Array[Dictionary] of queued analytics events.

flush_completed

• API：public

signal flush_completed(result: Dictionary)

flush 完成时发出。失败结果也会通过该信号通知。

参数：

名称	说明
result	flush 结果。

结构：

• result: Dictionary with at least success: bool; may include accepted, error, dry_run, or transport-specific fields.

flush_failed

• API：public

signal flush_failed(result: Dictionary)

flush 失败时额外发出。

参数：

名称	说明
result	失败结果。

结构：

• result: Dictionary with success: false and an optional error field.

属性

config

• API：public

var config: GFAnalyticsConfig = GFAnalyticsConfig.new()

当前配置。

payload_builder

• API：public

var payload_builder: Callable = Callable()

可选载荷构建回调。签名为 func(batch: Array) -> Dictionary。

transport_callback

• API：public

var transport_callback: Callable = Callable()

可选自定义传输回调。签名为 func(payload: Dictionary) -> Dictionary。

response_parser

• API：public

var response_parser: Callable = Callable()

可选响应解析回调。签名为 func(response_code: int, body: PackedByteArray, fallback_accepted: int) -> Dictionary。

方法

init

• API：public

func init() -> void:

初始化事件队列、会话 ID 和关闭监听。

dispose

• API：public

func dispose() -> void:

释放事件队列、HTTP 节点和关闭监听。

tick

• API：public

func tick(delta: float) -> void:

推进运行时逻辑。

参数：

名称	说明
delta	本帧时间增量（秒）。

configure

• API：public

func configure(analytics_config: GFAnalyticsConfig) -> void:

替换分析配置。

参数：

名称	说明
analytics_config	新配置。

identify

• API：public

func identify(client_id: String) -> void:

设置稳定客户端标识。

参数：

名称	说明
client_id	客户端标识。

track

• API：public

func track(event_name: StringName, properties: Dictionary = {}) -> void:

记录一个事件。

参数：

名称	说明
event_name	事件名。
properties	事件属性。

结构：

• properties: Dictionary[String, Variant] copied into the queued event properties.

flush

• API：public

func flush() -> void:

立即上报一批事件。

shutdown

• API：public

func shutdown(flush_remaining: bool = true) -> void:

停止继续接收事件，并可选 flush 当前队列。

参数：

名称	说明
flush_remaining	是否尝试 flush 剩余事件。

get_queue_size

• API：public

func get_queue_size() -> int:

获取当前队列长度。

返回：队列长度。

get_session_id

• API：public

func get_session_id() -> String:

获取当前会话标识。

返回：会话标识。

get_client_id

• API：public

func get_client_id() -> String:

获取当前客户端标识。

返回：客户端标识。

clear_queue

• API：public

func clear_queue() -> void:

清空本地事件队列。

capture_context

• API：public

func capture_context() -> Dictionary:

采集通用运行环境上下文。

返回：上下文字典。

结构：

• return: Dictionary with platform, engine, engine_version, screen size, locale, and timezone fields.