服务端集成 · 事件采集 · Lua SDK

介绍 Gravity Engine Lua SDK 的环境要求、安装初始化、事件追踪和用户属性管理，并提供参数说明与代码示例。

概述

Gravity Engine Lua SDK 是一个用于数据采集和上报的工具，帮助开发者轻松集成事件追踪和用户行为分析功能。在接入前，请先阅读接入前准备。服务端接入 Lua SDK，完成事件的服务端报送功能，您需要注意以下几点：

服务端 SDK仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 initialize 方法完成；
客户端和服务端 SDK使用的用户 client id 需要保持一致；
在客户端完成 initialize 方法调用之后，服务端 SDK才能开始做事件采集上报，否则上报不成功；
服务端 SDK接入事件上报时，请参考元事件页面下关于事件的详情属性；
请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（$city、$province、$country、$browser、$browser_version 属性可以不上报，引力后端会自动采集）；
关于属性的更多信息，请您参考事件属性页面。

1. 环境要求

Lua版本：5.1.5+

2. 安装集成

资源下载: 下载地址

导入 GEDataSdk.lua

local GEAnalytics = require("GEDataSdk")

3. 初始化配置

基础配置

local GEAnalytics = require("GEDataSdk")

SERVER_URL = 'https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___'

local function getDebugConsumer()
    return GEAnalytics.GEDebugConsumer(SERVER_URL)
end

local function getBatchConsumer()
    return GEAnalytics.GEBatchConsumer(SERVER_URL, 20, 50)
end

GEAnalytics.enableLog(true)

-- local consumer = getDebugConsumer()
local consumer = getBatchConsumer()

--- init SDK with consumer
local sdk = GEAnalytics(consumer, false, true)

核心功能

1. 事件追踪

如需上报自定义事件，您必须先在元事件中添加，否则会上报失败！

您可以调用 track 方法，记录用户自定义事件。

您需要先在元事件中添加自定义事件，然后调用 track 方法上报自定义事件。

local properties = {}
for i = 0, 100, 1 do
    properties["idx"] = i
    properties["productNames"] = { "Lua", "hello" }
    properties["productType"] = "Lua book"
    properties["producePrice"] = 80
    properties["shop"] = "xx-shop"
    properties["#os"] = "1.1.1.1"
    properties["date"] = os.date()
    properties["date1"] = os.date("%Y-%m-%d %H:%M:%S")
    sdk:track(clientId, "$AdClick", properties)
end

事件的名称是字符串类型。
Key 为该属性的名称，为字符串类型。
Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组。

2. 用户属性管理

设置用户属性（覆盖）

对于一般的用户属性，您可以调用 userSet 进行设置，使用该接口上传的属性将会覆盖原有的属性值。

properties = {}
properties['user_name'] = "xxx"
sdk:userSet(clientId, properties)

初始化用户属性（仅首次设置有效）

对于只在首次设置时有效的属性，我们可以使用 userSetOnce 记录这些属性。与 userSet 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据。因此，userSetOnce 适用于为用户设置首次激活时间、首次注册时间等属性。

properties = {}
properties['prop_set_once'] = "once"
sdk:userSetOnce(clientId, properties)

累加用户属性

对于数值型的用户属性，可以使用 userIncrement 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。

properties = {}
properties['TotalRevenue'] = 100
sdk:userIncrement(clientId, properties)

用户属性取最大值

对于数值型的用户属性，可以使用 userMax 比较数值大小，保存较大的值。

properties = {}
properties['TotalRevenue'] = 1000
sdk:userMax(clientId, properties)

用户属性取最小值

对于数值型的用户属性，可以使用 userMin 比较数值大小，保存较小的值。

properties = {}
properties['TotalRevenue'] = 1
sdk:userMin(clientId, properties)

用户属性追加

对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 userAppend 记录列表型属性。

properties = {}
properties['prop_list_type'] = { 'a', 'a', 'b' }
sdk:userAppend(clientId, properties)

用户属性去重追加

调用 userUniqAppend 对 Array 类型的用户数据去重追加元素。

properties = {}
properties['prop_list_type'] = { 'a', 'a', 'b', 'c' }
sdk:userUniqAppend(clientId, properties)

重置用户属性

如果需要重置已设置的某个用户属性，可以调用 userUnset 进行重置。

properties = {}
properties['user_name'] = ""
sdk:userUnset(clientId, properties)

清空用户属性

调用 userDel 方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

sdk:userDel(clientId)

3. 数据管理

立即上报数据

sdk:flush()

注意：频繁调用 flush() 会影响性能，建议在重要操作后调用。

关闭 SDK

sdk:close()

在应用关闭前调用，确保缓存数据不会丢失。

完整示例

local GEAnalytics = require("GEDataSdk")

SERVER_URL = 'https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___'

local function getDebugConsumer()
    return GEAnalytics.GEDebugConsumer(SERVER_URL)
end

local function getBatchConsumer()
    return GEAnalytics.GEBatchConsumer(SERVER_URL, 20, 50)
end

GEAnalytics.enableLog(true)

-- local consumer = getDebugConsumer()
local consumer = getBatchConsumer()

--- init SDK with consumer
local sdk = GEAnalytics(consumer, false, true)

local clientId = "_test_client_id_0"
local properties = {}

for i = 0, 100, 1 do
    properties["idx"] = i
    properties["productNames"] = { "Lua", "hello" }
    properties["productType"] = "Lua book"
    properties["producePrice"] = 80
    properties["shop"] = "xx-shop"
    properties["#os"] = "1.1.1.1"
    properties["date"] = os.date()
    properties["date1"] = os.date("%Y-%m-%d %H:%M:%S")
    sdk:track(clientId, "$AdClick", properties)
end

properties = {}
properties['prop_set_once'] = "once"
sdk:userSetOnce(clientId, properties)

properties = {}
properties['user_name'] = "xxx"
sdk:userSet(clientId, properties)

properties = {}
properties['user_name'] = ""
sdk:userUnset(clientId, properties)

properties = {}
properties['prop_list_type'] = { 'a', 'a', 'b' }
sdk:userAppend(clientId, properties)

properties = {}
properties['prop_list_type'] = { 'a', 'a', 'b', 'c' }
sdk:userUniqAppend(clientId, properties)

properties = {}
properties['TotalRevenue'] = 100
sdk:userIncrement(clientId, properties)

properties = {}
properties['TotalRevenue'] = 1000
sdk:userMax(clientId, properties)

properties = {}
properties['TotalRevenue'] = 1
sdk:userMin(clientId, properties)

sdk:userDel(clientId)

properties = nil

sdk:flush()
sdk:close()

Lua SDK

概述