===== PAGE 1 ===== OPPO⼴告主APP数据回传接⼝⽂档v3.23 版本 内容 v3.2 ⽀持⼴告主回传oaid-md5，type 新增值 type = 2 oadi md5加密 v3.3 dataType 新增值 21：⻓留⾼质量⼈群 v3.4 dataType 新增值 22：应⽤付费次数，新增字段payId v3.5 dataType 新增值 23：⻓留⾃定义⼈群 v3.6 dataType 新增值 24：快应⽤付费次数 v3.7 dataType 新增值 25：付费流⽔ v3.8 dataType 新增值 26：质量分 v3.9 ascribeType值优化 v3.10 dataType 新增值 27：完件 v3.11 payId、payAmount是否必填信息补充 v3.12 dataType 新增值 28：应⽤关键⾏为，dataType已有值20从游戏/ 应⽤关键⾏为变更为游戏关键⾏为 v3.13 新增字段⾦融授信⾦额、通⽤后端效果质量分 dataType 新增⾏业质量策略使⽤值，201到224 v3.14 新增【通⽤后端效果质量分】对部分⾏业的回传建议说明 v3.15 dataType新增值200：特殊回传（⽤于⾏业客户回传历史数据的短 期处理） v3.16 新增dataCategory枚举值 v3.17 新增dataCategory枚举值 V3.18 更新⽇期：2025-08-27 更新⼈：章丹阳 更新内容：新增2.2 请求体两个参数userIdType和keyTrackInfo的回传说 明，补充了2.3响应参数说明，以⽀持智能分包归因结果的回传 v3.19 更新⽇期：2025-12-02更新⼈：卿婷 更新内容：补充2.2 请求体参数userIdType回传说明，当使⽤智能分包 回传时userIdType必填；补充了2.3响应参数说明，ret 1007：使⽤了智能 分包回传但未提供userIdType v3.20 新增dataType枚举值231 v3.21 新增dataType枚举值 232-浏览岗位，233-B端认证 增加channel字段⽤于助攻的枚举 更新⼈：宋乐怡 ===== PAGE 2 ===== 公共部分 1.1请求头（本⽂档接⼝均需要添加如下请求头） 编码⽅式统⼀使⽤UTF-8 1.2 Signature签名 (1) 计算⽅式 使⽤md5对数据进⾏签名: md5( postData + timestamp + salt)，md5后转⼩写 2. 签名示例 数据准备： postData数据（示例）： {"payAmount":100,"adId":101097648,"appType":1,"clientIp":"127.0.0.1","dataType":1, "ascribeType":1,"channel":1,"imei":"XJMyaLt8fDlv4a9b8/0RNQ==","type":1,"pkg":"co m.oppo.test","mac":"TEViR6jSgD/lECBl3Ah70eNy2gUQrQlekHkWqEGkZsU=","timesta mp":1571995483916} 注意：postData为请求的body json字符串，组成签名的json与body中的json必须完全⼀ 致，不可对该json进⾏添加任何空格和转义符。 timestamp：1571995483916，salt：e0u6fnlag06lc3pl md5加密： contents = postData + timestamp + salt（中间不加任何字符）= v3.22 新增dataType枚举值 234-注册次留，235-发消息&对话， 32-54 第9-31⽇留存 v3.23 更新⽇期：2026-05-28 更新⼈：⻩辉焱 更新内容：请求头header新增鉴权参数ownerToken 字段 类型 说明 是否必 须 signature string 根据签名算法计算得到的字符串，⻅ 签名算法1.2 是 timestamp string 时间戳转换为字符串（long毫秒） 是 Content-Type string 固定值：application/json 是 ownerToken string 营销平台⽣成的ominitoken 否 字段 解释 postData post的json格式数据 timestamp 时间戳（long毫秒） salt OPPO提供，Salt: e0u6fnlag06lc3pl ===== PAGE 3 ===== {"payAmount":100,"adId":101097648,"appType":1,"clientIp":"127.0.0.1","dataType ":1,"ascribeType":1,"channel":1,"imei":"XJMyaLt8fDlv4a9b8/0RNQ==","type":1,"pk g":"com.oppo.test","mac":"TEViR6jSgD/lECBl3Ah70eNy2gUQrQlekHkWqEGkZsU=" ,"timestamp":1571995483916}1571995483916e0u6fnlag06lc3pl 使⽤md5加密：md5(contents)= ce14fcc22abd7461e860263a8da983eb 1.3 加密算法 请求中的imei与mac字段均需通过AES算法进⾏加密，并且将加密后的⼆进制数据通过 base64编码为字符串。为了⽅便配置，示例中的密钥是经过base64处理后的字符串 (base64Key)。base64Key在接⼊时由OPPO提供。 Base64Key: XGAXicVG5GMBsx5bueOe4w== （1）java示例 import java.security.GeneralSecurityException; import java.security.Key; import javax.crypto.Cipher; import javax.crypto.spec.SecretKeySpec; import org.apache.commons.codec.binary.Base64; public class Demo { public static String encode(byte[] data, String base64Key) throws GeneralSecurityException { final Key dataKey = new SecretKeySpec(Base64.decodeBase64(base64Key), "AES"); Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5Padding"); cipher.init(Cipher.ENCRYPT_MODE, dataKey); byte[] encryptData = cipher.doFinal(data); return Base64.encodeBase64String(encryptData).replaceAll("\r", "").replaceAll("\n", ""); } } （2）php示例(仅供参考) 1.4 ownerToken鉴权 鉴权⽬的 ⽤于建⽴平台与⼴告主之间安全可信的数据通道，保障⼴告主的投放权益： 保护转化数据资产：仅授权⽅可写⼊回传数据，杜绝第三⽅伪造、篡改或恶意刷量； 降低对账与排查成本：请求来源可追溯、责任可界定，出现数据异议时可快速定位； 提升投放效果稳定性：确保模型训练样本真实可靠，归因结果更精准 如何⽣成token 与OPPO营销平台Omni API权限认证⾥的token保持⼀致： public function encrypt($input, $base64Key){ return openssl_encrypt($input, ‘AES-128-ECB’,base64_decode($base64Key),0,’’); } ===== PAGE 4 ===== https://adsfs.heytapimage.com/mp/static/omniapi/latest/index.html?id=1%20%E9%8 0%9A%E7%94%A8%E5%A3%B0%E6%98%8E ----------------------------------------------------------- token=base64(owner_id+“,”+api_id+“,”+time_stamp+“,”+sign) 所有内容使⽤半⻆逗号（,）按顺序拼接起来，再经过Base64编码。 owner_id：⽤户帐号id,为营销平台的⼴告主ID； api_id：API授权接⼊⽅唯⼀身份标识，在开通授权邮件中会与app_id⼀块提供； time_stamp：发起请求时的时间戳，精确到秒，这个值跟接收到请求时的服务器时间戳值偏差 （正或负）超过1200秒（20分钟）时，请求会被拒绝，要求调⽤⽅重新⽣成token（请使⽤ UTC+08:00中国北京时间）； sign：签名字符串，sign=sha1(api_id+api_key+time_stamp)，采⽤sha1加密算法⽣成签名串 （此处加号+代表字符串拼接，不是指要包含加号+），time_stamp为上⾯使⽤的时间戳； ----------------------------------------------------------- token在接⼝协议的位置 在回传接⼝的请求头部分, 参考1.1 token鉴权失败的返回信息 { ret:1008 msg: "ownerToken 鉴权失败 " } 1.数据回传接⼝ 2.1接⼝地址 POST请求：https://api.ads.heytapmobi.com/api/uploadActiveData 2.2请求体Body 1 2 3 4 字段 类型 说明 是否必须 样例 备注 userIdT ype int ⽤户标识类型。 1:oaid或imei，即点击监测归 因； 2：智能分包归因信息 。 注意： 当userIdType为1时，imei和 ouId必传其⼀，keytrackinfo可 选回传。 当userIdType为2时， keytrackinfo必传。 当⼴告主申请 使⽤智能分包 能⼒回传时必 填； 未接⼊智能分 包能⼒时⾮必 填 ===== PAGE 5 ===== keyTrac kInfo string 智能分包归因信息。 ⼴告主应⽤客户端从OPPO商 店客户端查询到的智能分包归 因信息"key_track_info"。只需 回传查询到的原始的完整的字 符串内容，不需要额外处理， 包含原始的下载时间戳、等完 整信息。 当此字段为必填时，需确保 keytrackinfo字段有值。 OPPO侧对有值校验通过时将 返回“ret=0”，表示回传成功。 同时OPPO侧将对其中的 trackId或adTraceId字段进⾏ 是否有值的判断，返回给⼴告 主参考，但不影响成功回传。 当 userIdType=2 ，此字段是必 填 当 userIdType=1 ，此字段是选 填。 {     "key_trac k_ref": " {\"adId\":\" 3700438\",\ "trackId\":\" 512cf5d5a1 3e30fd5527 36cb188e2f 32\"}",     "ext": " {\"download _start_time\ ":17568152 62855,\"adT raceId\":\"1 - VwdhGy7uR 2n8H1wM0y 7xPLFYnn2l 2HjRhWERM eA73LXjaYg Cc0+YqN57 nCLXDsd3A DEg+hb\\\/ JbufJuqk+nF 3W5AtD\\\/ kQyvoR3Wyi XR10oKk=\" ,\"adSmartC hannelId\":\ "enforceMo ckSmartCha nnelId\"}",     "status_c ode": "200" } imei string imei原⽂经过AES加密后的 值，加密算法参考表格下⽅ 当userIdType = 1时，必传其 ⼀ 当 userIdType=2 ，此字段是选 填。 加密前： 8681230399 27020 加密后： XJMyaLt8fDl v4a9b8/0RN Q== ===== PAGE 6 ===== ouId string oaid原⽂经过AES加密后的 值，加密算法参考表格下⽅ reques tId string 请求id 是 mac string 客户端mac经过AES加密后 的值,加密说明⻅2.3 否 加密前： d7:1b:3e:0 0:14:b3 加密后： TEViR6jSg D/lECBl3A h70eNy2gU QrQlekHkW qEGkZsU= clientIp string 事件发⽣时的客户端ip，如 210.210.210.210 否 127.0.0.1 timesta mp long 事件发⽣的时间戳(毫秒)， 如1522221766623 是 157199548 3916 pkg string 包名，如com.xxx 如果是快应⽤，要填快应⽤ id，如100137 是 com.oppo.t est，要填投 放应⽤的包 名，不要依 赖监测链接 上报的pkg 字段 ===== PAGE 7 ===== dataTy pe int 转化数据类型： 1、激活，2、注册，3、游 戏付费，4、次留，5、应⽤ 内授信，6、应⽤内下单 （电商），7、应⽤付费 8、⾃定义⽬标， 9、第3⽇ 留存 10、第4⽇留存， 11、第5⽇留存 12、第6⽇ 留存， 13、第7⽇留存， 14、第8⽇留存，15、拉 活，16、快应⽤付费，17、 次留（DP）18、卸载激活 19、快应⽤关键⾏为 20、 游戏关键⾏为 21、⻓留⾼ 质量⼈群（废弃） 22、应 ⽤付费次数 23、⻓留⾃定 义 24、快应⽤付费次数 25、付费流⽔ 26、质量分 27、完件 28、应⽤关键⾏ 为 32、第9⽇留存 33、第10 ⽇留存 34、第11⽇留存 35、第12⽇留存 36、第13 ⽇留存 37、第14⽇留存 38、第15⽇留存 39、第16 ⽇留存 40、第17⽇留存 41、第18⽇留存 42、第19 ⽇留存 43、第20⽇留存 44、第21⽇留存 45、第22 ⽇留存 46、第23⽇留存 47、第24⽇留存 48、第25 ⽇留存 49、第26⽇留存 50、第27题留存、 51、第 28⽇留存 52、第29⽇留存 53、第30⽇留存 54、第31 ⽇留存 ---⾏业质量策略使⽤--- 200-特殊回传 【电商】 下单（沿⽤已有6-应⽤内下 单） 201-商品加购 202-商品收藏 203-电商取消订单 225-商品浏览 是 1 ===== PAGE 8 ===== 226-商品搜索 227-跳转结算界⾯ 228-调起⽀付⻚⾯/调起⽀ 付宝⽀付⻚⾯ 222-⾼价值⽤户 【⾦融】 27-完件（沿⽤已有27-完 件） 5-授信（沿⽤已有5-应⽤内 授信） 204-进件 205-开户 206-⼊⾦ 207-⽤信/放款 208-交易（⾦融） 209-投保 210-保单升级 211-退保 231-⽤信/放款⾦额   【教育】 212-正价课购买 213-正价课到课 214-正价课完课 215-添加⽼师 216-低价课购买 217-低价课到课 218-低价课完课 219-退课 【招聘】 220-创建简历 221-投递简历 232-浏览岗位 233-B端认证 【游戏】 223-游戏注册 224-游戏付费 【社交】 229 app主⻚ ===== PAGE 9 ===== 230 充值⻚ 【AI】 234 注册次留 235 发消息&对话 【⽹服】 236 特殊标记⼈群 payId string 付费交易Id 否（但 dataType=22 /25 必填） custom Type int ⾃定义⽬标类型：dataType 填了8之后补充，枚举值与 客户沟通后补充 否 channe l int 渠道： 1、OPPO 2、⼀加 0、其他 *仅助攻回传时启⽤： 3、巨量引擎 4、腾讯⼴告 5、快⼿磁⼒引擎 6、百度 7、⼩红书 8、穿⼭甲 9、优量汇 是 1 type int 0： ⽆md5加密、原值（默 认为0） 1：imei md5 加密 2：oaid md5 加密 是 1 appTyp e int 应用类别： 1 应用 2 游戏 3 快 应用 0 其他，默认 1 应用 否 1 ===== PAGE 10 ===== payAm ount long 付 费 金 额 （ 单 位：分） 备注： 应⽤付费ltv1：客户必须回 传⾸次应⽤付费 （datatype=7）&⾸⽇内每 ⼀笔付费流⽔ （datatype=25） 例如： ⽤户imei1被xx应⽤拉新预 算触达并在当⽇产⽣2笔付 费流⽔,分别为6元和38元， 需要回传3条数据明细，分 别为： 1.datatype=7 payAmount='' （回传⽤户⾸次付费6元的 ⾏为数据，告知平台该⽤户 产⽣了付费转化） 2.datatype=25 payAmount=600 （回传该⽤户当⽇⾸次付费 ⾦额） 3.datatype=25 payAmount=3800 （回传该⽤户当⽇第⼆次付 费⾦额） 应⽤付费ltv7：客户必须回 传⾸次应⽤付费 （datatype=7）&7⽇内每 ⼀笔付费流⽔ （datatype=25） （回传示例同上，除回传⾸ 次付费事件datatype=7外， 7⽇内每笔付费数据均需按 标准回传） 否 100 该字段 传值 时。 datatyp e填25 ascribe Type int 归因类型：1：⼴告主归 因，0：OPPO归因（默认或 者不填即为0） 是 1 快应⽤必须 选1⼴告主 归因 adId long ⼴告主回传转化数据时，附 带已经归因好的⼴告id。对 应营销平台上的⼴告创意id 是 679063897 ===== PAGE 11 ===== reques tId string 请求id 否 quality Score float 质量分 否 0-1 最多回 传两位⼩数 淘宝专 ⽤ creditL ine long ⾦融授信⾦额(单位：分) 否 100 ===== PAGE 12 ===== commo nQualit yScore float 通⽤后端效果质量分 备注： 1.⾦融⾏业回传规范： 【⽅式1】：授信⾦额区间- ->回传质量分 0-3k（含3k）-->0.15 3-5k（含5k）-->0.30 5-8k（含8k）-->0.45 8-10k（含10k）-- >0.60 10-12k（含12k）-- >0.75 12k+以上-->0.90 【⽅式2】：若上述分档不 适⽤业务情况，可⾃⾏按照 业务实际情况映射为0-1之 间的⼩数回传，确保 ①质量分分布与授信⾦额呈 正相关②⾄少有六个及以上 的质量区间分档。 例： 0,02 | 0.19 | 0.24| 0.28| 0.54| 0.62| 0.83| 0.91| 0.97 【操作备注】： 回传质量分时，dataType转 化数据类型选择26-质量 分，与转化⾏为事件区分， 分两条分别回传 2.社交⾏业回传规范： 【⽅式】：付费⾦额区间-- >回传质量分 0-6元（含6元）-->0.1 6-15元（含15元）-- >0.2 15-30元（含30元）-- >0.3 30-50元（含50元）-- >0.4 50-100元（含100元）- ->0.5 100-200元（含200 元）-->0.6 200-300元（含300 元）-->0.7 否 0-1 最多回 传两位⼩数 该字段 传值 时。 datatyp e填26 ===== PAGE 13 ===== 2.3返回值Response 300-400元（含400 元）-->0.8 400-500元（含500 元）-->0.9 500元以上-->1.0 3.旅游⾏业回传规范：(⽤户 后效质量-->回传质量分) 【⽅式】根据业务⾃定义⽤ 户质量综合指标，映射为0- 1之间的⼩数回传，确保 ①质量分分布与授信⾦额呈 正相关②⾄少有六个及以上 的质量区间分档。 例： 0,02 | 0.19 | 0.24| 0.28| 0.54| 0.62| 0.83| 0.91| 0.97 dataCa tegory int 0：常规回传，1：⾏业优化 模型，2：助攻，3:品牌（默 认或者不填即为0） 是 字段 类型 说明 是否必须 ret int 返回码，0正常，1001参数校验失败， 1002未知错误，1007使⽤智能分包回传 但未提供userIdType, 1008ownerToken 鉴权失败 注意：如果是签名错误的话会返回http status 403 是 msg string 如果有错误，则返回错误信息 否 传参情况 响应码 提示语 当userIdType = 1时，imei和 ouId同时为空。 1001 imei/ouId/androidId/requestId cannot be all empty! 当userIdType = 2时， keyTrackInfo为空 1001 keyTrackInfo is null! 当userIdType = 2时， keyTrackInfo不为空。 keyTrackInfo中解析出来的 trackId和adTraceId同时为空 0 traceId & trackId are all empty! ===== PAGE 14 ===== 2.4请求示例 （1）Header （2）Body （3）Postman截图： 应⽤已经在智能分包⽩名单 中，但userIdType未填写 1007 ⽩名单客户必须提供 userIdType 当ownerToken不为空，且鉴 权失败 1008 ownerToken鉴权失败 signature ce14fcc22abd7461e860263a8da983eb Content-Type application/json timestamp 1571995483916 {"payAmount":100,"adId":101097648,"appType":1,"clientIp":"127.0.0.1","dataTyp e":1,"ascribeType":1,"channel":1,"imei":"XJMyaLt8fDlv4a9b8/0RNQ==","type":1," pkg":"com.oppo.test","mac":"TEViR6jSgD/lECBl3Ah70eNy2gUQrQlekHkWqEGkZ sU=","timestamp":1571995483916}