sdk
/
wt-game
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

no message

Browse Source
tags/v0.0.4
zhuxianglong 2 months ago
parent aa73c0790c
commit a021a60fb3
1 changed files with 90 additions and 70 deletions
Show Stats Download Patch File Download Diff File

160
point/README.md
Unescape Escape View File

@ -25,40 +25,51 @@ go get gitea.weitiangame.com/sdk/wt-game/point
package main package main
import ( import (
"gitea.weitiangame.com/sdk/wt-game/point" "gitea.weitiangame.com/sdk/wt-game/point"
"go.uber.org/zap" "go.uber.org/zap"
) )
func main() { func main() {
logger, _ := zap.NewProduction() logger, _ := zap.NewProduction()
// 创建单例上报实例（自动注入client_id） // 创建单例上报实例（自动注入client_id）
reporter := point.New("your_client_id", logger) // client_id 请在TapDB控制台获取
// logger 为zap.Logger实例，可选, 用于记录日志, 也可传nil不记录
reporter := point.New("your_client_id", logger)
} }
``` ```
#### 基础事件上报 #### 基础事件上报
```go ```go
func main() { func main() {
reporter := point.New("game_123", zap.NewExample()) logger, _ := zap.NewProduction()
reporter := point.New("game_123", logger)
eventData := map[string]interface{}{ // 事件数据, 具体字段请参考TapDB文档
"event": "player_login", // 文档地址:https://docs.tapdb.com/zh/collecting-data/sdk/ios-sdk
"distinct_id": "user_888", eventData := map[string]interface{}{
"properties": map[string]interface{}{ "name": "charge", // 事件名，固定为 charge
"level": 5, "user_id": "your-user-id", // 必需。用户 ID。必须和 SDK 的 setUser 接口传递的 userId 一样，并且该用户已经通过 SDK 接口进行过推送
"region": "cn", "type": "track", // 必需。数据类型，请确保传入的值为 track
}, "properties": map[string]interface{}{
} "ip": "8.8.8.8", // 可选。充值用户的 IP
"order_id": "100000", // 可选。长度大于 0 并小于等于 256。订单 ID。
if resp, err := reporter.Event(eventData); err != nil { "amount": 100, // 必需。大于 0 并小于等于 100000000000。充值金额。单位分，即无论什么币种，都需要乘以 100
"virtual_currency_amount": 100, //获赠虚拟币数量，必传，可为 0
"currency_type": "CNY", // 可选。货币类型。国际通行三字母表示法，为空时默认 CNY。参考：人民币 CNY，美元 USD；欧元 EUR
"product": "item1", // 可选。长度大于 0 并小于等于 256。商品名称
"payment": "alipay", // 可选。长度大于 0 并小于等于 256。充值渠道
},
}
if resp, err := reporter.Event(eventData); err != nil {
logger.Error("上报失败", zap.Error(err)) logger.Error("上报失败", zap.Error(err))
} else { } else {
logger.Info("上报成功", logger.Info("上报成功",
zap.Int("status", resp.StatusCode()), zap.Int("status", resp.StatusCode()),
zap.String("trace_id", resp.Header().Get("X-Trace-Id"))) zap.String("trace_id", resp.Header().Get("X-Trace-Id")))
} }
} }
``` ```
### 🔧 高级用法 ### 🔧 高级用法
@ -66,31 +77,32 @@ func main() {
#### 启用调试模式 #### 启用调试模式
```go ```go
func main() { func main() {
// 初始化时启用调试和CURL输出 // 初始化时启用调试和CURL输出
reporter := point.New("client_123", logger). reporter := point.New("client_123", logger).
Debug(). // 显示请求详情 Debug(). // 打印显示请求详情
Curl() // 生成CURL命令 Curl() // 打印生成CURL命令
reporter.Event(map[string]interface{}{ reporter.Event(map[string]interface{}{
"event": "ad_click", "event": "ad_click",
"properties": map[string]interface{}{ "properties": map[string]interface{}{
"ad_id": "banner_001", "ad_id": "banner_001",
}, },
}) })
} }
``` ```
#### 自定义HTTP客户端 #### 自定义HTTP客户端
```go ```go
func main() { func main() {
customClient := ahttp.New(&ahttp.Config{ // 创建自定义HTTP客户端, 可以设置超时时间和重试次数，具体参数请参考ahttp库
Timeout: 10 * time.Second, customClient := ahttp.New(&ahttp.Config{
Retries: 3, Timeout: 10 * time.Second,
}).Client() Retries: 3,
}).Client()
point.New("game_123", logger).
SetClient(customClient). // 注入自定义客户端 point.New("game_123", logger).
Event(eventData) SetClient(customClient). // 注入自定义客户端
Event(eventData)
} }
``` ```
@ -101,8 +113,7 @@ func main() {
| **单例模式** | 全局唯一实例，避免重复创建资源 | | **单例模式** | 全局唯一实例，避免重复创建资源 |
| **线程安全** | 基于互斥锁保护配置变更，内置线程安全HTTP客户端 | | **线程安全** | 基于互斥锁保护配置变更，内置线程安全HTTP客户端 |
| **调试支持** | 支持请求详情输出和CURL命令生成 | | **调试支持** | 支持请求详情输出和CURL命令生成 |
| **自动重试** | 依赖底层HTTP客户端的重试策略（默认3次） | | **自动重试** | 依赖底层HTTP客户端的重试策略（默认3次） | |
| **数据隔离** | 自动复制传入数据，防止并发修改 |
### ⚠️ 注意事项 ### ⚠️ 注意事项
1. `New()` 方法为单例模式，首次调用后配置不可变更 1. `New()` 方法为单例模式，首次调用后配置不可变更
@ -120,7 +131,7 @@ func main() {
### 📖 Introduction ### 📖 Introduction
`point` is a thread-safe event reporting SDK designed for TapDB, featuring a clean API and concurrency-safe mechanisms. Built with singleton pattern and HTTP connection pooling, ideal for high-concurrency data reporting scenarios. `point` is a thread-safe event reporting SDK designed for TapDB, providing a simple API and concurrency-safe mechanisms. Built with a singleton pattern, it includes an HTTP connection pool and automatic retry policies, suitable for high-concurrency data reporting scenarios.
GitHub URL: [gitea.weitiangame.com/sdk/wt-game/point](https://gitea.weitiangame.com/sdk/wt-game/point) GitHub URL: [gitea.weitiangame.com/sdk/wt-game/point](https://gitea.weitiangame.com/sdk/wt-game/point)
@ -144,7 +155,9 @@ import (
func main() { func main() {
logger, _ := zap.NewProduction() logger, _ := zap.NewProduction()
// Create singleton instance (auto-injects client_id) // Create a singleton reporter (auto-injects client_id)
// client_id should be obtained from the TapDB console
// logger is an optional zap.Logger instance; pass nil to disable logging
reporter := point.New("your_client_id", logger) reporter := point.New("your_client_id", logger)
} }
``` ```
@ -152,14 +165,23 @@ func main() {
#### Basic Event Reporting #### Basic Event Reporting
```go ```go
func main() { func main() {
reporter := point.New("game_123", zap.NewExample()) logger, _ := zap.NewProduction()
reporter := point.New("game_123", logger)
// Event data structure, refer to TapDB documentation for specific fields
// Documentation: https://docs.tapdb.com/en/collecting-data/sdk/ios-sdk
eventData := map[string]interface{}{ eventData := map[string]interface{}{
"event": "player_login", "name": "charge", // Event name, fixed as 'charge'
"distinct_id": "user_888", "user_id": "your-user-id", // Required. User ID, must match the userId set via SDK's setUser interface
"type": "track", // Required. Data type, must be 'track'
"properties": map[string]interface{}{ "properties": map[string]interface{}{
"level": 5, "ip": "8.8.8.8", // Optional. User's IP address
"region": "cn", "order_id": "100000", // Optional. Order ID (length <= 256)
"amount": 100, // Required. Amount in cents (must be > 0)
"virtual_currency_amount": 100, // Required. Virtual currency received (can be 0)
"currency_type": "CNY", // Optional. Currency code (default: CNY)
"product": "item1", // Optional. Product name (length <= 256)
"payment": "alipay", // Optional. Payment method (length <= 256)
}, },
} }
@ -180,21 +202,18 @@ func main() {
func main() { func main() {
// Enable debug features during initialization // Enable debug features during initialization
reporter := point.New("client_123", logger). reporter := point.New("client_123", logger).
Debug(). // Show request details Debug(). // Print request details
Curl() // Generate CURL commands Curl() // Generate CURL commands for debugging
reporter.Event(map[string]interface{}{ reporter.Event(eventData)
"event": "ad_click",
"properties": map[string]interface{}{
"ad_id": "banner_001",
},
})
} }
``` ```
#### Custom HTTP Client #### Custom HTTP Client
```go ```go
func main() { func main() {
// Create a custom HTTP client with specific timeout and retry settings
// Refer to the ahttp library documentation for configuration details
customClient := ahttp.New(&ahttp.Config{ customClient := ahttp.New(&ahttp.Config{
Timeout: 10 * time.Second, Timeout: 10 * time.Second,
Retries: 3, Retries: 3,
@ -208,22 +227,23 @@ func main() {
### ✨ Key Features ### ✨ Key Features
| Feature | Description | | Feature | Description |
|---------------------|-----------------------------------------------------------------| |---------------------|-----------------------------------------------------------------------------|
| **Singleton** | Global single instance prevents resource duplication | | **Singleton** | Single global instance prevents resource duplication |
| **Thread-Safe** | Mutex-protected configuration with built-in safe HTTP client | | **Thread-Safe** | Mutex-protected configuration with built-in thread-safe HTTP client |
| **Debug Support** | Request diagnostics and CURL command generation | | **Debug Support** | Request detail logging and CURL command generation |
| **Auto Retry** | Built-in retry policy (default 3 attempts) | | **Auto Retry** | Built-in retry policy (default 3 attempts) via underlying HTTP client |
| **Data Isolation** | Automatic data copying prevents concurrent modification |
### ⚠️ Important Notes ### ⚠️ Important Notes
1. `New()` uses singleton pattern, configurations are immutable after first call 1. The `New()` method uses singleton pattern; configurations are immutable after the first call
2. Use `Debug()` and `Curl()` only in development environments 2. Use `Debug()` and `Curl()` only in development environments
3. Event data must contain `event` field, `distinct_id` is recommended 3. Event data must contain required fields as per TapDB documentation. For example:
4. Check request parameters for non-2xx HTTP responses - `user_id` is required for user-related events
5. Implement batch processing for large-scale data reporting - `type` must be set to `track` for tracking events
4. Check request parameters if receiving non-2xx HTTP responses
5. Implement batch processing when reporting large volumes of data
### 🤝 Contributing ### 🤝 Contributing
[Contribution Guide](CONTRIBUTING.md) | [Open an Issue](https://gitea.weitiangame.com/sdk/wt-game/point/issues) [Contribution Guide](CONTRIBUTING.md) | [Open an Issue](https://gitea.weitiangame.com/sdk/wt-game/point/issues)
[⬆ Back to Top](#中文) [⬆ Back to Top](#english)
Write Preview
Loading…
Cancel
Save