bygdata/pkg/devtodev

devtodev SDK (Go)

Minimal Go SDK for devtodev Data API 2.0 event reporting.

Install

Use as a local module or set your module path in go.mod.

Usage

package main

import (
    "context"
    "time"

    devtodev "devtodev-sdk"
)

func main() {
    client := devtodev.NewClient("YOUR_APP_ID")

    payload := devtodev.Payload{
        Reports: []devtodev.Report{
            {
                DeviceID: "device-123",
                Packages: []devtodev.DevtodevPackage{
                    *devtodev.NewReporter(nil, "device-123").NewPackage().
                        WithLanguage("en").
                        WithCountry("US").
                        Append(devtodev.RawEvent{
                            "code":      "ce",
                            "timestamp": time.Now().UnixMilli(),
                            "level":     5,
                            "name":      "custom_event",
                            "parameters": map[string]interface{}{
                                "level": 5,
                            },
                        }),
                },
            },
        },
    }

    if err := client.Send(context.Background(), payload); err != nil {
        panic(err)
    }
}

Event Builder

This SDK uses a Reporter -> Package -> Event builder flow. Build one or more events, append them into a package, then report once.

client := devtodev.NewClient("YOUR_APP_ID")

reporter := devtodev.NewReporter(client, "device-123")
pkg := reporter.NewPackage().
    WithPlatform("web").
    WithLanguage("en").
    WithCountry("US").
    WithIP("127.0.0.1").
    WithAppVersion("1.0.0")

pkg.Append(devtodev.NewDeviceInfoEvent(time.Now().UnixMilli(), map[string]interface{}{
    "platform": "ios",
    "device":   "iPhone14,3",
}))

pkg.Append(devtodev.NewCustomEvent(time.Now().UnixMilli(), 1, "custom_event", map[string]interface{}{
    "score": 123,
}, nil))

_, _ = pkg.Report(context.Background())

中文事件文档

Service Events

• Device Info（di）：设备信息上报。必填字段：code=di、timestamp。新用户必须先发送该事件，否则不会注册用户。
• Session Start（ss）：会话开始。必填字段：code=ss、timestamp、level。
• User Engagement（ue）：用户活跃/心跳，记录活跃时长。必填字段：code=ue、timestamp、level、length（秒）。
• Setting User Tracking Status (GDPR)（ts）：用户追踪授权状态。必填字段：code=ts、timestamp、trackingAllowed（bool）。
• Alive（al）：应用存活/心跳。必填字段：code=al、timestamp。

User properties

• People（pl）：用户属性更新。必填字段：code=pl、timestamp、level、parameters（用户属性键值对）。

Basic Events

• Custom Event（ce）：自定义事件。必填字段：code=ce、timestamp、level、name；parameters 可选。
• Real Payment（rp）：真实支付（IAP）。必填字段：code=rp、timestamp、level、productId、orderId、price、currencyCode。
• Onboarding / Tutorial（tr）：新手引导。必填字段：code=tr、timestamp、level、step。
• Virtual Currency Payment（vp）：虚拟货币消费。必填字段：code=vp、timestamp、level、purchaseAmount、purchasePrice、purchaseType、purchaseId。
• Currency Accrual（ca）：虚拟货币获得。必填字段：code=ca、timestamp、level，且 bought 与 earned 至少提供一个。
• Current Balance（cb）：当前余额。必填字段：code=cb、timestamp、level、balance。
• Level Up（lu）：升级。必填字段：code=lu、timestamp、level；balance/spent/earned/bought 可选。
• Progression Event（pe）：进度事件。必填字段：code=pe、timestamp、level、name、parameters。parameters 内必填：success、duration。

Secondary Events

• Referral（rf）：邀请推荐/安装来源。必填字段：code=rf、timestamp。
• Ad Impression（adrv）：广告展示。必填字段：code=adrv、timestamp、ad_network、revenue。
• Social Connect（sc）：社交绑定。必填字段：code=sc、timestamp、level、socialNetwork。
• Social Post（sp）：社交分享。必填字段：code=sp、timestamp、level、socialNetwork、postReason。

事件相关性说明

• Session Start（ss）需要搭配 User Engagement（ue）才能完整统计会话时长。
• Device Info（di）必须作为新用户的首个事件上报；建议每次会话开始时也上报一次。
• Alive（al）在用户超过 5 分钟没有任何事件时，需要上报以保持“在线”状态展示。
• Setting User Tracking Status（ts）当用户拒绝追踪时必须上报；trackingAllowed=false 会触发删除该用户数据并禁止继续收集，若之后改为 true 则视为新用户。
• Session Start（ss）/ User Engagement（ue）/ Alive（al）可通过 sessionId 关联为同一会话。
• Currency Accrual（ca）不建议按“每笔交易”上报，应按 5-10 分钟聚合上报；当用户等级变化时应中断并上报一次聚合结果。
• Current Balance（cb）不应对同一用户一天上报超过一次。
• Referral（rf）每个用户仅需上报一次；若已接入 AppsFlyer 等广告追踪或 devtodev 自定义回调，可不再上报。
• Progression Event（pe）的 parameters.source 用于串联上一个关卡/区域，便于形成进度链路。

Notes

• Default endpoint: https://api.devtodev.com/v2/analytics/report?appId=YOUR_APP_ID
• Payload size limit is 2 MB uncompressed.
• Timestamps are in milliseconds since epoch.
• For new users, send the Device Info event (code: "di") first so the user is registered.
• SDK validates required fields (reports, deviceId, packages, events, code, timestamp) before sending.
• Content-Type values follow the API: application/json, application/zstd, application/gzip.
• Use SendWithResponse if you need response details (status, headers, body, parsed JSON).
• Retries happen on common transient HTTP statuses and network errors.

Customize

client := devtodev.NewClient("YOUR_APP_ID")
client.Endpoint = "https://api.devtodev.com/v2/analytics/report"
client.Retry.MaxAttempts = 5
client.Retry.BaseDelay = 300 * time.Millisecond
client.Retry.MaxDelay = 3 * time.Second

// Compression options
client.Compression = devtodev.CompressionGzip // or CompressionZstd / CompressionNone