menu
Is this helpful?

# 自定义通道接入文档

# 1.简介

TE运营模块的 自定义通道 定义了一种 API,其目的是在于连接下游客户方任何消息或类消息系统。

客户经过较为轻量的 REST API 对接开发,即可快速支持非TE运营模块内置的触发通道。

具体的调用链路参考下图:

  1. 首先TE运营模块(Engage)会读分析模块(Analytics)事件数据和用户数据,进行目标人群的计算。
  2. 结合目标人群,并且组装好消息的内容。TE运营模块会分批发 HTTP 请求到您配置的一个自定义通道服务。
  3. 您自身的自定义通道服务接收到http的调用,获取到请求内容之后,可自行做格式转化、拼接其他业务数据,入异步处理队列 等操作,并最终调用其他任何内部或外部的消息/类消息系统,可能调用的系统举例:
    • 游戏邮件系统
    • 游戏公告系统
    • 封号系统
    • 短信系统
    • 第三方推送系统
  4. 处理完成之后(不包括异步处理流程),按照约定格式返回本次请求的处理结果,如果有处理失败的数据,需要明确返回该数据的序号和失败原因。TE运营模块会记录处理失败的数据。
  5. 回执事件数据回收(可选)
    • 如果推送到游戏的邮件系统,那么可以在用户打开游戏邮件时埋点,把“点击邮件”作为一个点击推送的埋点事件,并且按照约定带上相关透传参数,以便实现更精准的触达环节的漏斗分析。

# 2.自定义通道服务

为与TE运营模块的 自定义通道 对接,您需要开发一个 HTTP Endpoint Server。其应遵循的 API 定义见下文。

# 2.1 入参出参格式定义

# 自定义通道 Request

服务的入参,由TE运营模块构造生成,采用POST方式,Content-Type设定为application/json。请求体request_body是一个JSONArray,支持一批次发送多条消息数据。 每条消息数据,代表给一个用户发送一个特定内容的消息。

WARNING

注意,TE运营模块的 自定义通道 在一个请求体中包含了多个用户的触发消息,这个是为了方便下游方便批量处理,从而提升发送的效率。 一个批次包含多少个用户,支持自定义配置。

参数示例如下:

// 请求入参格式
[
    {"push_id":"accountid123987001","custom_params":{"gameuid":"123acb001","name":"张三",...},"params":{"title":"每日活动",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
    ,{"push_id":"accountid123987002","custom_params":{"gameuid":"123acb002","name":"李四",...},"params":{"title":"每日活动",...},"#ops_receipt_properties":{"ops_task_id":"0050",...}}
]

// 具体每条消息的入参格式
{
    //通道的发送id,一般是用户唯一id,如账号id或者角色id。由运营在在'TE运营模块-通道管理'侧定义
    "push_id": "accountid123987001",
    
    //模板参数,此参数下的具体参数内容可以在'TE运营模块-通道管理'侧定义
    "params": {
        "title": "每日活动",
        "content": "你好张三,快来参加活动吧!",
        //对象组
        "attachment": [
            {
                "item_id":"xx1",
                "count":"5"
            },
            {
                "item_id":"xx2",
                "count":"10"
            }
        ]
    },
    //自定义参数,可以带出用户属性,此参数下的具体参数内容可以在'TE运营模块-通道管理'侧定义
     "custom_params": {
         "zone_id":"17281",
         "name": "张三"
    },
    //通道回执属性,此参数由TE运营模块系统默认添加,用于后续数据统计,通常业务侧无需解析,透传到下游即可。下游上报时注意把这个json对象直接上报,不要toString之后再上报
    "#ops_receipt_properties": {   
        "ops_project_id": 1,  //对应TE项目id
        "ops_task_id": "0050", //对应一个运营任务
        "ops_task_instance_id": "0050_2023-01-01",  //对应一次运营任务实例
        "ops_task_exec_detail_id": "17795",  //对应一次任务实例的推送
        "ops_request_id": "f7b66eb7-3363-4a46-a402-601a64b45f76", //对应一次推送中的一次batch请求,同一次请求里的所有ops_request_id都是相同的,并且请求重试时此ID不会变化,客户业务系统如果要对请求做幂等校验,可用这个字段。
        "ops_push_language": "default",  //对应任务推送语言
        "ops_exp_group_id": "122" //对应任务AB实验分组id
    }
}
参数名 参数类型 是否必填 参数描述 备注
push_id String 推送ID 具体参数字段可以在'运营设置-通道管理-发送ID'侧定义
params Object 模板参数 需要在推送时候由运营填写的一些通道参数,比如推送的内容。 具体参数内容可以在'运营设置-通道管理--内容模版'侧定义
custom_params Object 自定义参数 需要由系统自动带出的推送目标用户的用户属性 具体参数内容可以在'运营设置-通道管理-自定义参数'侧定义
#ops_receipt_properties Object TE运营模块回执字段 TE运营模块系统默认添加 下游系统如果需要观测消息的点击情况,则需要在点击事件直接透传上报此字段 在任务目标设置的转化事件中,无需上报此字段
> 模板参数,自定义参数的Key的命名规范:采用下划线分隔命名,参数由字母数字下划线组成,且带头字符只能是下划线和字母 > 注意:在params和custom_params的参数中,对于任何类型的数据(如整数,小数,日期等类型),在发送请求时,所有的字段全部转为字符串进行处理

# 自定义通道 Response

参数示例如下:

{
    "return_code": 0,
    "return_message": "success",
    "data": {
        // fail_list里面的每个元素是失败的对象信息,包含报错信息及报错对象的序号,报错对象序号从1开始。假设:发送5个对象信息,序号为1-5,成功3个失败2个,其中第2个和第4个失败,则返回如下
        "fail_list": [{
            "index": 2,
            "message": "需要推送的玩家token信息不存在"
        }, {
            "index": 4,
            "message": "push id not found"
        }]
    }
}
参数名 参数类型 是否必有 参数说明
return_code Integer 返回码 0 代表成功(或者部分成功) 1 代表失败
return_message String 返回信息
data Object 返回数据
data.fail_list Array 假如return_code=0, data.fail_list为[]或null时,会认为全部成功 data.fail_list不为空,则为部分失败,失败的明细为list里定义的。 如果业务上不存在部分失败的情况,直接传[]就行; 注意: 1. 一些不可用的PushId校验,建议在接口处理逻辑里面做前置校验,以便在fail_list里返回给数数。这会让任务的触发成功指标统计更加准确。 1. 失败列表里的对象index属性代表序号,编号从1开始,不是从0开始! 1. message字段不是必填,但是强烈建议返回,便于异常时候的问题排查 假如return_code=1,无论data.fail_list里传了什么,都认为全部失败。

# 2.2 请求鉴权

鉴权功能默认不开启。如果自定义通道 server无需鉴权可跳过此段。

如果要支持鉴权,需要在配置通道的时候打开鉴权开关,发送端会将签名添加到http请求头中,Key为X-TE-OPS-Signature。服务端需要根据密钥与Request Body进行HmacSHA1签名并生成signature,然后和发送端的签名进行比对,比对一致代表认证通过。

签名算法的Java实现参考:

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
/*
   HmacSHA1签名算法
   
   secretKey是客户配置的密钥
   requestBody是请求内容的JSONString
*/
public static String HmacSHA1(String secretKey,String requestBody) throws Exception {
    String signature = (new HmacUtils(HmacAlgorithms.HMAC_SHA_1,secretKey)).hmacHex(requestBody)
    return signature;
}

签名算法的PHP实现参考:

/**
 * HmacSHA1签名算法
 * @param $secretKey : 客户配置的密钥
 * @param $requestBody : 请求内容的JSONString
 * @return string 签名值
 */
function HmacSHA1($secretKey, $requestBody) {
    return hash_hmac('sha1', $requestBody, $secretKey);
}

# 2.3 请求并发性能

为了保证消息推送速度,自定义通道服务支持的并发越高越好,建议可以支持100以上TPS。同时,数数的智能运营模块可以按照下游自定义通道服务的并发能力上限,进行相应的限流配置。

# 2.4 请求和结果完整测试例子

// 请求信息
curl -X POST "http://localhost:8999/v1/自定义通道/test/sample" 
-H "accept: */*" 
-H "X-TE-OPS-Signature: 2e1ee1eeaDA121"
-H "Content-Type: application/json" 
-d "[{\"push_id\":\"3e156c91-f039-4d48-9b6f-72b76111af24\",\"costom_params\":{\"name\":\"张三\"},\"params\":{\"title\":\"每日活动\",\"content\":\"你好张三,快来参加活动吧!\"},\"#ops_receipt_properties\":{\"ops_task_id\":\"0050\",\"ops_request_id\":\"f7b66eb7-3363-4a46-a402-601a64b45f76\",\"ops_task_instance_id\":\"31\",\"ops_project_id\":1}}]"

// 返回结果
{
  "data": {
      "fail_list": []
  },
  "return_code": 0,
  "return_message": "success"
}

# 自定义通道可配置参数介绍

以下参数默认后台配置,如需修改可联系数数科技客户成功

配置项 可选值 默认值 配置描述
发送限流 -1,[1,10000] 不限流 单位:次/秒 设置为-1,代表不限流 设置为1-10000的数字,例如500,代表每秒钟最多接受请求500次下游自定义通道服务器
发送批大小 [1,500] 100 表示一次调用参数的JsonArray里包含多少个元素 批次大小设置大,可以提高消息发送的效率 批次大小设置小,发送速度会比较慢,但是可靠性会更高 推荐设置为100,最大可设置500。
超时时间 [0,600] 60 单位:秒 http请求socket超时时间,默认是60s 如果设置了<=0,相当于不超时
失败重试次数 [0,10] 0 为了避免业务上重复推送,默认0次,即不重试 如果配置了>0的值,当接口超时或者接口返回return_code!=0会走重试逻辑
失败重试时间间隔 [0,600] 5 单位:秒 默认每隔5s重试一次
返回值强校验 开启,不开启 开启 开启后,TE运营模块服务会校验下游服务器返回的response的格式,如果不符合上面自定义通道 response参数定义规范认为失败 例子:假设超时时间设置为5s 如果不开启返回值强校验,自定义通道服务在5s内正常返回,且返回值HTTP 200 无 Body,TE运营模块认为本次调用成功 如果开启返回值强校验,自定义通道服务在5s内正常返回,且返回值HTTP 200 无 Body或者Body格式和约定的规范不一致,TE运营模块认为本次调用失败

# 通道配置页面示例

参数 说明 备注
通道名称 自定义通道的名称(用于显示、选择) 唯一性校验
通道URL 接收消息推送的接口地址 支持同一个URL地址配置多个通道
发送ID 接收消息的目标用户ID类型,比如发送邮件用到的是用户的角色ID(role_id) 发送ID需要作为用户属性上报 在目标用户人数预估时会过滤发送ID为空的用户
通道鉴权 自定义通道鉴权方式 默认关闭,可按需开启
触达漏斗设置 漏斗步骤关联的元事件名 可选开启
内容模板 该通道发给用户的具体内容的模板,支持文本、动态文本、数值和对象组等字段类型,如发送邮件通道可以通过对象组类型配置道具内容(道具ID和道具数量),在触达任务前端页面展示出来,供配置运营任务的的运营人员填写 字段:参数的名称,发送时消息体使用 字段名称:在创建任务的时候展示的字段 字段类型:文本、动态文本、数值和对象组等 提示文案:在创建任务的时候输入框提示(非必填) 是否必填:是/否(单选,默认是)
自定义参数 根据通道要求选择性添加,该参数为透传 非必填 字段: 参数的名称,发送时消息体使用 关联字段:字段关联的用户属性,发送消息体时字段值使用该属性值默认值: 可选,已设置默认值,当属性值为空时使用默认值;未设置默认值,属性值为空时返回空值

# 采集点击推送事件

通过自定义通道推送的消息可以按需在客户端/服务端采集点击事件,采集方式可参考数数数据接入手册中的上报事件的方式,事件名可以自定义,事件数据需要获取自定义通道下发消息中的#ops_receipt_properties字段并且整体作为一个对象属性上报即可。如果有其他分析场景,此事件中也可以加上其他字段属性。

注意:属性字段名一定是#ops_receipt_properties,类型是对象,不可随意更改。改了字段名,修改了字段内部的内容或者误把字段作为一个文本属性上报,都会导致后续数据使用异常

代码示例:

JSONObject properties = new JSONObject();
//从自定义通道下发的message消息体中获取到json结构的ops_receipt_properties对象,整体作为一个对象属性上报
JSONObject opsReceiptProperties = message.get("#ops_receipt_properties")
//注意:属性名必须是ops_receipt_properties,不可随意更改。事件名可以自定义
properties.put("#ops_receipt_properties",opsReceiptProperties);
//properties对象内容示例: "#ops_receipt_properties":{"ops_task_id":"0062","ops_project_id":2,"ops_task_instance_id":"62","ops_request_id":"967ea854-2c42-490b-9c33-c1792ea637ec"}
instance.track("ops_push_click",properties);