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 具体参数字段可以在'TE运营模块-通道管理-推送ID'侧定义
params Object 否 模板参数 需要在推送时候由运营填写的一些通道参数，比如推送的内容。 具体参数内容可以在'TE运营模块-通道管理-模板参数'侧定义
custom_params Object 否 自定义参数 需要由系统自动带出的推送目标用户的用户属性 具体参数内容可以在'TE运营模块-通道管理-自定义参数'侧定义
#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);

← Android推送集成文档 →