# 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.Package{
                    {
                        Language: "en",
                        Country:  "US",
                        Events: []devtodev.Event{
                            {
                                "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 Helpers

This SDK includes a `Reporter` wrapper. Each event has its own function and sends a single report.

```go
client := devtodev.NewClient("YOUR_APP_ID")

reporter := devtodev.NewReporter(client, "device-123")
reporter.Package = devtodev.Package{
    Language: "en",
    Country:  "US",
}

// Device Info (di)
_, _ = reporter.DeviceInfo(context.Background(), time.Now().UnixMilli(), map[string]interface{}{
    "platform": "ios",
    "device":   "iPhone14,3",
})

// Custom Event (ce)
_, _ = reporter.CustomEvent(context.Background(), time.Now().UnixMilli(), 1, "custom_event", map[string]interface{}{
    "score": 123,
}, nil)
```

## 中文事件文档

**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
```