星图直播小手柄组件监测服务说明
2025-03-19 18:08:59
📢 注意：此文档监测说明仅适配星图游戏行业直播场景任务
一、小手柄监测下发流程图
二、监测逻辑
1、监测事件范围
| 场景 | 图片 |
|
|  |
|  | |
|
|  |
|  | |
|  | |
|
| |
| ||
|
2、监测链接宏参数
通过约定指定格式的字符串，用以代表将来将要替换的字段位置，这个格式我们统称为“宏”。参数的格式为“__参数__”，详细说明参考下文。
3、游戏事件
- •游戏事件定义：
事件名称 | 事件定义 | event_type值 |
激活事件 | 用户首次打开APP | active |
登录事件 | 用户每次完成帐号登录行为 | login |
消费事件 | 用户成功支付/成功退款行为 | active_pay |
- •涉及用户范围：所有归因至小手柄监测链接的转化，都应按照本文档约定回传深度事件，回传不区分是否属于商业化流量或自然流量（换句话说就是归因到通过抖音小手柄组件的转化，全部都需回传，不管是不是通过广告体系买量）
三、监测链接配置规范
1、格式
(1)监测链接的前缀格式为：https://XXX.XXX.com?
(2)“宏”参数的格式为“__参数__”，其中：
- •参数必须全部大写，小手柄支持宏参数请见下方
- •“__参数__”格式中参数两边为双下划线，即参数左右两边均为两个连续的英文字符'_'
- •广告主可以根据自己的需要选择具体填写哪些参数，支持参数详见参数列表
- •监测链接支持大小写字母、数字以及下划线字符。
2、请求格式
- •通信协议：支持通过HTTPS通道进行请求通信。
- •请求方法：支持接收HTTPS GET方法请求，这种方式下请求参数需要包含在请求的URL中。
- •字符编码：UTF-8
3、说明
- •宏参数必须全大写，否则无法回传对应参数值。
- •监测链接长度大小不得超过 10K。
- •监测链接不能是下载链接。
- •监测链接必须支持连通。
- •监测链接不能包含非法字符，包括但不限于如下列表：
序号 | 非法字符 | 字符解释 |
1 | % | url path 中出现的单个的 %，后面不跟2位16进制数；转义字符中的 % 没有问题 |
2 | 空格 | url 中出现的空格 |
3 | // | url path 中出现的连续 // |
4、宏参数列表
1）指派类任务、投稿类任务非效果结算
示例：
2）投稿任务按效果结算
示例：
四、游戏事件回传
💕💕特别提醒：一定要按照本文档要求回传正确的参数及完整的信息！错传漏传参数将影响数据的准确性
1、请求方式
- •通信协议：支持通过HTTPS通道进行请求通信
- •请求方法：支持HTTPS POST方法发送请求
- •字符编码：UTF-8
- •Content-Type : application/json
- •注意事项：
- ◦传递数据必须统一记录在extra内的ad_extra_data，参考下面的数据格式
- ◦iOS上报登录事件之前，先要上报激活事件
- ◦ad_extra_data的具体数据结构参考「回传事件数据结构(ad_extra_data)」一节
2、请求体格式
- 1.{
- 2. "event_type": "event_type",
- 3. "context": {
- 4. "ad": {
- 5. "callback": "B.vgcH5jYqoquzezEA"
- 6. }
- 7. },
- 8. "extra": {
- 9. // 回传事件信息统一在这里提供
- 10. "ad_extra_data": "{\"game_user_id\":\"1234\"}"
- 11. }
- 12.}
3、如何获取callback？
在填写的监测链接中，需要有一个关键宏信息__CALLBACK_PARAM__，完整的监测链接应该是这样：
经过信息替换以后的监测链接是这样
- 1.{
- 2. "event_type": "active",
- 3. "context": {
- 4. "ad": {
- 5. "callback": "EPHk9cX3pv4CGJax4ZENKI7w4MDev_4C",
- 6. }
- 7. },
- 8. "timestamp": 1604888786102
- 9.}
4、回传事件数据结构(ad_extra_data)
1）激活事件
无需传递任何字段，特别注意：ActiveExtra是空结构体，即"{}"，不是空字符串
名称 | 类型 | 含义 | 样例 |
|
2）登录事件
3）付费事件
5、返回值
- 1.{
- 2. "code":0,
- 3. "message":"成功"
- 4.}
枚举值 | message | 说明 |
0 | 成功 | |
10 | 服务暂时不可用，请稍后重试 | 比较严重的错误，请立即联系字节同学 |
100 | 无效的请求,请求数据解析失败 | 如果参数的 body 按照 json 解析错误，就会报这个错。 |
102 | 参数：event_type无效 | event_type 不在我们列举的值中 |
103 | 参数：callback无效 | callback 解析错误 |
6、示例代码
Golang
- 1.import (
- 2. "encoding/json"
- 3. "errors"
- 4. "io/ioutil"
- 5. "net/http"
- 6. "strings"
- 7.)
- 8.
- 9.// ActiveExtra 激活事件回传结构
- 10.type ActiveExtra struct {}
- 11.
- 12.// IOSLoginExtra ios系统登录事件回传结构
- 13.type IOSLoginExtra struct {
- 14. GameUserID string `json:"game_user_id"` // 必填
- 15. GameUserRegisterTime int64 `json:"game_user_register_time"` // 秒级时间戳
- 16. GameUserLastLoginTime int64 `json:"game_user_last_login_time"` // 秒级时间戳
- 17. GameInstallTime int64 `json:"game_install_time"` // 秒级时间戳
- 18.}
- 19.
- 20.// AndroidLoginExtra 安卓系统登录事件回传结构
- 21.type AndroidLoginExtra struct {
- 22. GameUserID string `json:"game_user_id"` // 必填，
- 23. LoginTime int64 `json:"login_time"` // 必填，秒级时间戳
- 24.}
- 25.
- 26.// PayExtra 付费事件回传结构
- 27.type PayExtra struct {
- 28. OS string `json:"os"` // 必填，android/ios
- 29. OrderType int32 `json:"order_type"` // 必填，1 成功 2 退款
- 30. GameUserId string `json:"game_user_id"` // 必填
- 31. GameOrderId string `json:"game_order_id"` // 必填，订单唯一标记
- 32. ProductId string `json:"product_id"` // 可不传
- 33. ProductName string `json:"product_name"` // 可不传
- 34. ProductDesc string `json:"product_desc"` // 可不传
- 35. TotalAmount int64 `json:"total_amount"` // 必填，总金额，单位为分
- 36. PayTime int64 `json:"pay_time"` // 必填，秒级时间戳
- 37.}
- 38.
- 39.type CallBackMsg struct {
- 40. EventType string `json:"event_type"`
- 41. Context ContextData `json:"context"`
- 42. Extra map[string]string `json:"extra"`
- 43.}
- 44.
- 45.type ContextData struct {
- 46. AD map[string]string `json:"ad"`
- 47.}
- 48.
- 49.const (
- 50. ActiveEventType = "active" // 激活事件
- 51. LoginEventType = "login" // 登录事件
- 52. PayEventType = "active_pay" // 消费事件
- 53.)
- 54.
- 55.// SendCallbackMsg 发送转化回传事件
- 56.// @param eventType 事件类型，上面的 ActiveEventType/LoginEventType/PayEventType
- 57.// @param callbackParam 在监测链接中传递的callback参数，对应宏参数 CALLBACK_PARAM
- 58.// @param retExtraStr 需要传递回平台的数据，json化字符串。不同类型的事件有不同结构，ActiveExtra / PayExtra / ...
- 59.func SendCallbackMsg(eventType, callbackParam, retExtraStr string) error {
- 60. // 回传事件上报地址
- 61. retURL := `https://analytics.oceanengine.com/api/v2/conversion`
- 62. client := &http.Client{}
- 63.
- 64. // 构建传递的参数
- 65. callBackMsg := CallBackMsg{
- 66. EventType: eventType,
- 67. Context: ContextData{
- 68. AD: map[string]string{"callback": callbackParam},
- 69. },
- 70. Extra: map[string]string{
- 71. // 特别注意：retExtraStr不能为空字符串，可以是空json结构体
- 72. // retExtraStr可以用"{}"，不能用""
- 73. "ad_extra_data": retExtraStr,
- 74. },
- 75. }
- 76.
- 77. infoBytes, _ := json.Marshal(callBackMsg)
- 78. req, _ := http.NewRequest("POST", retURL, strings.NewReader(string(infoBytes)))
- 79. resp, err := client.Do(req)
- 80. if err != nil {
- 81. return err
- 82. }
- 83. defer resp.Body.Close()
- 84. if resp.StatusCode != 200 {
- 85. return errors.New("resp StatusCode not 200")
- 86. }
- 87.
- 88. // 检查返回值code，code不为0时参考接入文档的返回值
- 89. type respMsg struct {
- 90. Code int64 `json:"code"`
- 91. Message string `json:"message"`
- 92. }
- 93. var result respMsg
- 94. body, err := ioutil.ReadAll(resp.Body)
- 95. if err == nil {
- 96. err = json.Unmarshal(body, &result)
- 97. }
- 98. if err != nil {
- 99. return err
- 100. }
- 101. if result.Code != 0 {
- 102. return errors.New("send Callback Msg err StatusCode")
- 103. }
- 104. return nil
- 105.}
Java
Python
C++