From a021a60fb377c952d13a5da2f6b75da537a6ce8c Mon Sep 17 00:00:00 2001 From: zhuxianglong <56494565@qq.com> Date: Wed, 22 Jan 2025 17:14:27 +0800 Subject: [PATCH] no message --- point/README.md | 160 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 90 insertions(+), 70 deletions(-) diff --git a/point/README.md b/point/README.md index 429d285..1c33d7a 100644 --- a/point/README.md +++ b/point/README.md @@ -25,40 +25,51 @@ go get gitea.weitiangame.com/sdk/wt-game/point package main import ( - "gitea.weitiangame.com/sdk/wt-game/point" - "go.uber.org/zap" + "gitea.weitiangame.com/sdk/wt-game/point" + "go.uber.org/zap" ) func main() { - logger, _ := zap.NewProduction() - - // 创建单例上报实例（自动注入client_id） - reporter := point.New("your_client_id", logger) + logger, _ := zap.NewProduction() + + // 创建单例上报实例（自动注入client_id） + // client_id 请在TapDB控制台获取 + // logger 为zap.Logger实例，可选, 用于记录日志, 也可传nil不记录 + reporter := point.New("your_client_id", logger) } ``` #### 基础事件上报 ```go -func main() { - reporter := point.New("game_123", zap.NewExample()) - - eventData := map[string]interface{}{ - "event": "player_login", - "distinct_id": "user_888", - "properties": map[string]interface{}{ - "level": 5, - "region": "cn", - }, - } - - if resp, err := reporter.Event(eventData); err != nil { + func main() { + logger, _ := zap.NewProduction() + reporter := point.New("game_123", logger) + // 事件数据, 具体字段请参考TapDB文档 + // 文档地址:https://docs.tapdb.com/zh/collecting-data/sdk/ios-sdk + eventData := map[string]interface{}{ + "name": "charge", // 事件名，固定为 charge + "user_id": "your-user-id", // 必需。用户 ID。必须和 SDK 的 setUser 接口传递的 userId 一样，并且该用户已经通过 SDK 接口进行过推送 + "type": "track", // 必需。数据类型，请确保传入的值为 track + "properties": map[string]interface{}{ + "ip": "8.8.8.8", // 可选。充值用户的 IP + "order_id": "100000", // 可选。长度大于 0 并小于等于 256。订单 ID。 + "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)) - } else { - logger.Info("上报成功", + } else { + logger.Info("上报成功", zap.Int("status", resp.StatusCode()), zap.String("trace_id", resp.Header().Get("X-Trace-Id"))) - } + } } + ``` ### 🔧 高级用法 @@ -66,31 +77,32 @@ func main() { #### 启用调试模式 ```go func main() { - // 初始化时启用调试和CURL输出 - reporter := point.New("client_123", logger). - Debug(). // 显示请求详情 - Curl() // 生成CURL命令 - - reporter.Event(map[string]interface{}{ - "event": "ad_click", - "properties": map[string]interface{}{ - "ad_id": "banner_001", - }, - }) +// 初始化时启用调试和CURL输出 +reporter := point.New("client_123", logger). +Debug(). // 打印显示请求详情 +Curl() // 打印生成CURL命令 + +reporter.Event(map[string]interface{}{ +"event": "ad_click", +"properties": map[string]interface{}{ +"ad_id": "banner_001", +}, +}) } ``` #### 自定义HTTP客户端 ```go func main() { - customClient := ahttp.New(&ahttp.Config{ - Timeout: 10 * time.Second, - Retries: 3, - }).Client() - - point.New("game_123", logger). - SetClient(customClient). // 注入自定义客户端 - Event(eventData) +// 创建自定义HTTP客户端, 可以设置超时时间和重试次数，具体参数请参考ahttp库 +customClient := ahttp.New(&ahttp.Config{ +Timeout: 10 * time.Second, +Retries: 3, +}).Client() + +point.New("game_123", logger). +SetClient(customClient). // 注入自定义客户端 +Event(eventData) } ``` @@ -101,8 +113,7 @@ func main() { | **单例模式** | 全局唯一实例，避免重复创建资源 | | **线程安全** | 基于互斥锁保护配置变更，内置线程安全HTTP客户端 | | **调试支持** | 支持请求详情输出和CURL命令生成 | -| **自动重试** | 依赖底层HTTP客户端的重试策略（默认3次） | -| **数据隔离** | 自动复制传入数据，防止并发修改 | +| **自动重试** | 依赖底层HTTP客户端的重试策略（默认3次） | | ### ⚠️ 注意事项 1. `New()` 方法为单例模式，首次调用后配置不可变更 @@ -120,7 +131,7 @@ func main() { ### 📖 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) @@ -144,7 +155,9 @@ import ( func main() { 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) } ``` @@ -152,14 +165,23 @@ func main() { #### Basic Event Reporting ```go 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{}{ - "event": "player_login", - "distinct_id": "user_888", + "name": "charge", // Event name, fixed as 'charge' + "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{}{ - "level": 5, - "region": "cn", + "ip": "8.8.8.8", // Optional. User's IP address + "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() { // Enable debug features during initialization reporter := point.New("client_123", logger). - Debug(). // Show request details - Curl() // Generate CURL commands + Debug(). // Print request details + Curl() // Generate CURL commands for debugging - reporter.Event(map[string]interface{}{ - "event": "ad_click", - "properties": map[string]interface{}{ - "ad_id": "banner_001", - }, - }) + reporter.Event(eventData) } ``` #### Custom HTTP Client ```go 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{ Timeout: 10 * time.Second, Retries: 3, @@ -208,22 +227,23 @@ func main() { ### ✨ Key Features -| Feature | Description | -|---------------------|-----------------------------------------------------------------| -| **Singleton** | Global single instance prevents resource duplication | -| **Thread-Safe** | Mutex-protected configuration with built-in safe HTTP client | -| **Debug Support** | Request diagnostics and CURL command generation | -| **Auto Retry** | Built-in retry policy (default 3 attempts) | -| **Data Isolation** | Automatic data copying prevents concurrent modification | +| Feature | Description | +|---------------------|-----------------------------------------------------------------------------| +| **Singleton** | Single global instance prevents resource duplication | +| **Thread-Safe** | Mutex-protected configuration with built-in thread-safe HTTP client | +| **Debug Support** | Request detail logging and CURL command generation | +| **Auto Retry** | Built-in retry policy (default 3 attempts) via underlying HTTP client | ### ⚠️ 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 -3. Event data must contain `event` field, `distinct_id` is recommended -4. Check request parameters for non-2xx HTTP responses -5. Implement batch processing for large-scale data reporting +3. Event data must contain required fields as per TapDB documentation. For example: + - `user_id` is required for user-related events + - `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 [Contribution Guide](CONTRIBUTING.md) | [Open an Issue](https://gitea.weitiangame.com/sdk/wt-game/point/issues) -[⬆ Back to Top](#中文) \ No newline at end of file +[⬆ Back to Top](#english) \ No newline at end of file