拉新拉活技术对接文档

文档更新记录

版本	作者	时间	备注
v1.0	张勇	2024.11.22	创建
v1.1	张勇	2025.02.12	更新
v1.2	张勇	2025.04.07	增加xy_ev参数

对接流程

新义提供投放的投放链接信息（如deeplink）
新义提供上报需要的 上报地址 report_key report_extras xy_ev 参数

API 跟踪接口参数说明

上报地址: 新义提供

参数名	描述	类型	必需	说明/示例
`action`	跟踪事件类型（如展示、点击）	字符串	是	`imp` 曝光, `click` 点击
`account_id`	媒体账户ID	字符串	否
`ad_id`	广告投放ID	字符串	否
`callback_url`	回调URL，用于接收事件完成通知	URL	是	`https%3A%2F%2Ftest.com%3Frequest_id%3D123`
`campaign_id`	广告计划ID	字符串	否
`idfa`	iOS设备的广告标识符	字符串	可选	`86DA2BC5-AAD3-4756-A8C1-D5736B1013EB`
`idfa_md5`	IDFA的MD5哈希值	字符串	可选	`aecc38a26c36765ae2d5baf741a87205`
`caid`	iOS设备CAID（URL编码的JSON）	JSON字符串	可选	见如下示例
`imei`	设备IMEI	字符串	可选	`123456789012345`
`imei_md5`	IMEI的MD5哈希值	字符串	可选	`58b9b9268acaef64ac6a80b0543357e6`
`ip`	用户设备的IP地址	字符串	是	`192.168.1.1`）
`mac`	设备MAC地址	字符串	否	`00:1A:2B:3C:4D:5E`
`make`	设备制造商	字符串	否	`Apple`、`Samsung`）
`material_id`	广告创意素材ID	字符串	否	`44554`
`model`	设备型号	字符串	否	`iPhone 12 Pro`、`Galaxy S21`）
`oaid`	安卓设备的匿名广告标识符	字符串	可选	`a1670e09e7564a91d896a6687dec095a34153e3335c1e598e60261bbe2ddb6a1`
`oaid_md5`	OAID的MD5哈希值	字符串	可选	`4a870af8c058e9ce56044563221f0bc1`
`os_type`	操作系统类型	字符串	是	`1`：iOS，`0`：Android
`request_id`	唯一请求ID，用于日志跟踪	字符串	是	`ad5d0e628cdd4ce7ab64a659b23cec17`
`ua`	用户代理字符串（浏览器/应用信息）	字符串	是	`Mozilla/5.0 (Linux; Android 12; RMX3461 Build/RKQ1.210503.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.54 Mobile Safari/537.36`
`report_key`	上报链接参数	字符串	是	新义提供，无需修改
`report_extras`	额外报告参数（URL编码的JSON）	JSON字符串	是	新义提供，无需修改
`xy_ev`	上报版本	字符串	否	新义提供，无需修改

注意事项

设备参数：
- iOS设备:idfa idfa_md5 caid 至少传一个
- 安卓设备: oaid oaid_md5 imei imei_md5 至少传一个
占位符替换：所有__XXX__需替换为实际值，没有为空（如__AD_ID__ → 12345）。
编码要求： callback_url需进行URL编码一次。

caid示例

[{ "caid": "bed47550547dc8d51c98b668eb690140","caid_md5": "27dc3f5a7c02e8cba6e699c3ee07b295","version": "20220501"}, {"caid": "cb187c190ba19b7863c803cb27ab2523", "caid_md5":"34ae823c759e5c0480867247c77462bb", "version": "20210501"}]

url encode 后的值
%5B%7B%20%22caid%22%3A%20%22bed47550547dc8d51c98b668eb690140%22%2C%22caid_md5%22%3A%20%2227dc3f5a7c02e8cba6e699c3ee07b295%22%2C%22version%22%3A%20%2220220501%22%7D%2C%20%7B%22caid%22%3A%20%22cb187c190ba19b7863c803cb27ab2523%22%2C%20%22caid_md5%22%3A%2234ae823c759e5c0480867247c77462bb%22%2C%20%22version%22%3A%20%2220210501%22%7D%5D

转化 (新义回传媒体)

新义会将曝光/点击上报地址里面的 callback_url 取出来, 解码, 在末尾加上 &event_type =$具体转化值，回传给媒体

事件枚举值：

转化类型	转化值
唤端	app_opened
首唤	first_app_opened
注册	registration
激活	activation
下单	order
购买	purchase
次日留存	d1_retention
商品详情浏览	product_detail_view
登录	login
关键行为	key_behavior

联调

媒体按照文档对接，将实际的宏参数替换
上报曝光、点击给到新义，确认接收正常
新义回传事件给到媒体，确保链路正常
没问题开始线上小量测试，上报/回调都正常，对接联调完成