141 lines
6.5 KiB
Markdown
141 lines
6.5 KiB
Markdown
# 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
|
||
|
||
```go
|
||
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.
|
||
|
||
```go
|
||
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
|
||
|
||
```go
|
||
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
|
||
```
|