Defold 分析与崩溃上报

对象_动作          推荐
level_start
level_complete
level_fail
item_purchase
shop_open
tutorial_step

不要用：StartLevel、start-level、开始关卡（中文名不利于聚合）

-- analytics.lua 对外接口
local M = {}

function M.track(name, props)
    local event = {
        name    = name,
        ts      = os.time() * 1000,
        session = M.session_id,
        props   = props or {},
    }
    M.enqueue(event)
end

return M

埋点 → 内存队列 → 达到阈值或定时 → 批量上报 → 成功则清空
                                          → 失败则回退到本地存储

-- analytics/queue.lua
local M = {
    items    = {},
    max_size = 100,
}

function M.push(event)
    table.insert(M.items, event)
    if #M.items > M.max_size then
        table.remove(M.items, 1)   -- 丢弃最旧事件，保护内存
    end
end

function M.drain(n)
    local batch = {}
    for i = 1, math.min(n, #M.items) do
        table.insert(batch, M.items[i])
    end
    for _ = 1, #batch do
        table.remove(M.items, 1)
    end
    return batch
end

return M

local FILE = "analytics_pending"

function M.persist()
    local ok, err = pcall(sys.save, FILE, M.items)
    if not ok then
        print("[analytics] 落盘失败:", tostring(err))
    end
end

function M.restore()
    local data = sys.load(FILE)
    if data and #data > 0 then
        M.items = data
        print("[analytics] 恢复待上报事件:", #data)
    end
end

local function post_batch(batch, on_done)
    local body = json.encode({ events = batch })
    local headers = {
        ["Content-Type"] = "application/json",
        ["X-Api-Key"]    = ANALYTICS_KEY,
    }
    http.request("https://api.example.com/v1/events", "POST", function(self, id, response)
        on_done(response.status == 200)
    end, headers, body)
end

local FLUSH_INTERVAL = 10.0     -- 每 10 秒尝试上报
local BATCH_SIZE     = 20

function update(self, dt)
    self.timer = (self.timer or 0) + dt
    if self.timer >= FLUSH_INTERVAL and not self.sending then
        self.timer = 0
        flush(self)
    end
end

function flush(self)
    if queue.size() == 0 then return end
    self.sending = true
    local batch = queue.drain(BATCH_SIZE)
    post_batch(batch, function(ok)
        self.sending = false
        if ok then
            print("[analytics] 上报成功:", #batch, "条")
        else
            -- 失败：把事件塞回队列头部，等待下次重试
            for i = #batch, 1, -1 do
                table.insert(queue.items, 1, batch[i])
            end
            queue.persist()
        end
    end)
end

function init(self)
    sys.set_error_handler(function(source, message, traceback)
        -- source: 出错的脚本或模块路径
        -- message: 错误描述
        -- traceback: 调用栈字符串
        print("[crash] source:", tostring(source))
        print("[crash] message:", tostring(message))
        report_crash(source, message, traceback)
    end)
end

1. 捕获     → sys.set_error_handler 拿到 source/message/traceback
2. 持久化   → 立即写入本地文件（网络此时往往不可靠）
3. 延迟上报 → 下次启动时检查待发送崩溃报告并上传

local CRASH_FILE = "crash_pending"

local function report_crash(source, message, traceback)
    local payload = {
        source    = tostring(source),
        message   = tostring(message),
        traceback = tostring(traceback),
        ts        = os.time(),
        app       = sys.get_application_info(),
        device    = sys.get_sys_info(),
        engine    = sys.get_engine_info(),
    }
    sys.save(CRASH_FILE, payload)   -- 同步落盘，确保退出前写入
    print("[crash] 崩溃报告已写入本地")
end

function init(self)
    local pending = sys.load("crash_pending")
    if pending and pending.message then
        post_crash(pending, function(ok)
            if ok then
                sys.save("crash_pending", {})   -- 上报成功才清空
                print("[crash] 历史崩溃补报成功")
            end
        end)
    end
    sys.set_error_handler(on_error)
end

local function capture_context(extra)
    local info = sys.get_sys_info()
    local app  = sys.get_application_info()
    return {
        platform     = info.system_name,
        os_version   = info.system_version,
        device       = info.device_model,
        manufacturer = info.manufacturer,
        language     = info.language,
        app_id       = app.identifier,
        version      = app.version,
        engine       = sys.get_engine_info().version,
        extra        = extra or {},
        trace        = debug.traceback("", 2),
    }
end

function analytics.set_context(key, value)
    analytics.context[key] = value
end

-- 进入关卡时记录
function on_level_start(self, level_id)
    analytics.set_context("level", level_id)
    analytics.set_context("player_hp", self.hp)
end

-- 面包屑：记录崩溃前最后 N 条操作
local MAX_BREADCRUMBS = 30
function analytics.add_breadcrumb(action, detail)
    table.insert(analytics.breadcrumbs, { action = action, detail = detail, ts = os.time() })
    while #analytics.breadcrumbs > MAX_BREADCRUMBS do
        table.remove(analytics.breadcrumbs, 1)
    end
end

冷启动 → 新会话
切后台超过 30 分钟再回来 → 新会话
切后台 30 分钟内回来 → 延续当前会话

local SESSION_TIMEOUT = 30 * 60     -- 秒

function analytics.check_session()
    local now = os.time()
    if not analytics.session_id or (now - analytics.last_active) > SESSION_TIMEOUT then
        analytics.session_id = generate_session_id()
        print("[analytics] 新会话:", analytics.session_id)
    end
    analytics.last_active = now
end

function on_message(self, message_id, message, sender)
    if message_id == hash("window_focus_lost") then
        analytics.track("app_background")
        analytics.flush_now()          -- 切后台是刷新的最佳时机
    elseif message_id == hash("window_focus_gained") then
        analytics.check_session()
    end
end

local ALLOWED_PROPS = {
    level = true, level_name = true, duration = true,
    item_id = true, price = true, currency = true,
    result = true, step = true, reason = true,
}

local function sanitize(props)
    local out = {}
    for k, v in pairs(props or {}) do
        if ALLOWED_PROPS[k] then out[k] = v end
    end
    return out
end

禁止：真实姓名、邮箱、手机号、IP 全地址、设备序列号
禁止：玩家输入的聊天内容、自定义昵称、精确地理位置
允许：机型、系统版本、语言、应用版本、匿名 ID

function analytics.set_consent(granted)
    analytics.consent = granted
    if not granted then
        queue.items = {}
        sys.save("analytics_pending", {})
        print("[analytics] 用户拒绝数据收集，已清空队列")
    end
end

function analytics.track(name, props)
    if not analytics.consent then return end
    queue.push(build_event(name, sanitize(props)))
end

local stats = { ok = 0, fail = 0 }

function track_result(ok)
    if ok then stats.ok = stats.ok + 1 else stats.fail = stats.fail + 1 end
    local total = stats.ok + stats.fail
    if total >= 20 and (stats.fail / total) > 0.3 then
        print(string.format("[analytics] 上报失败率过高: %.1f%%", stats.fail / total * 100))
    end
end

指纹 = hash(message + traceback 的前 3 行)

-- ======================================
-- 完整示例：analytics.lua 埋点模块骨架
-- 放在 /scripts/analytics.lua
-- ======================================

local M = {
    uid = nil, session_id = nil, last_active = 0,
    consent = false, context = {}, pending = {}, sending = false,
}

local ENDPOINT   = "https://api.example.com/v1/events"
local API_KEY    = "your-api-key"
local BATCH_SIZE = 20

local ALLOWED = { level = true, duration = true, result = true, item_id = true, price = true }

local function sanitize(props)
    local out = {}
    for k, v in pairs(props or {}) do
        if ALLOWED[k] then out[k] = v end
    end
    return out
end

function M.init()
    M.uid = string.format("u_%x", os.time())
    M.session_id = string.format("s_%x", math.random(1e8))
    M.consent = sys.get_config_string("analytics_consent", "false") == "true"
    sys.set_error_handler(function(source, message, traceback)
        sys.save("crash_pending", {
            source = tostring(source),
            message = tostring(message),
            traceback = tostring(traceback),
            ctx = M.context,
            sys = sys.get_sys_info(),
        })
        print("[analytics] 崩溃已记录:", tostring(message))
    end)
end

function M.track(name, props, priority)
    if not M.consent then return end
    table.insert(M.pending, {
        name = name, uid = M.uid, session = M.session_id,
        ts = os.time(), priority = priority or "normal",
        props = sanitize(props), ctx = M.context,
    })
    if #M.pending > 500 then table.remove(M.pending, 1) end
end

function M.flush(on_done)
    if M.sending or #M.pending == 0 then
        if on_done then on_done(false) end
        return
    end
    M.sending = true
    local batch = {}
    for i = 1, math.min(BATCH_SIZE, #M.pending) do
        table.insert(batch, M.pending[i])
    end
    for _ = 1, #batch do table.remove(M.pending, 1) end

    local headers = { ["Content-Type"] = "application/json", ["X-Api-Key"] = API_KEY }
    http.request(ENDPOINT, "POST", function(self, id, response)
        M.sending = false
        if response.status == 200 then
            print("[analytics] 上报成功:", #batch)
        else
            for i = #batch, 1, -1 do
                table.insert(M.pending, 1, batch[i])
            end
            sys.save("analytics_pending", M.pending)
        end
        if on_done then on_done(response.status == 200) end
    end, headers, json.encode({ events = batch }))
end

return M