接口文档SDK业务专题开发者工具

获取点击数据-API开发指南

点击数据接收指引

获取广告中的点击数据,需要四个步骤。

  1. 在转化跟踪工具中配置下发信息;
  2. 开发接收点击数据的接口;
  3. 进行联调,保证数据通路畅通;
  4. 在工具中打开数据转发状态。配置流程请参考《获取点击数据-配置指南》

接收点击接口介绍

接收点击接口用于腾讯广告将用户的点击行为信息发送给广告主,主要由广告主自定义的 Feedback URL和腾讯广告拼接的参数共同构成。实现此接口需要广告主提供广告主自定义的feedback URL,腾讯广告按照规则拼接参数后调用接收点击接口。

广告主利用Feedback URL接收点击数据,并返回正确的返回值后,腾讯广告即认为此次点击转发成功。为了保证点击的时效性,您接收到的实际转发的点击数有可能大于腾讯广告投放端显示的点击数。

Feedback URL 介绍

Feedback URL 是由广告主自定义的用于腾讯广告将点击数据传输给广告主的实现连接。广告主在腾讯广告投放端(e.qq.com)创建转化时,需要输入Feedback URL。

Feedback URL 要求:

  • 可以有参数,但不能包含符号:#
  • 不要占用平台可能下发的参数:click_time、click_id、advertiser_id、muid、ip、user_agent、app_type、appid、android_id、campaign_id、adgroup_id、creative_id、deeplink_url、agent_id、oaid、device_os_type、dest_url、adgroup_name、click_sku_id、process_time、product_type、request_id、site_set
  • 可以用http、https
  • 不能直接用ip,必须是正式的域名

示例如下:

示例1: http://www.example.com/gdt.cgi 正确(√)
示例2: http://www.example.com/gdt.cgi?source=gdt 可以添加参数(√)
示例3: https://www.example.com/gdt.cgi?muid=xxxxx&click_time=1406276499&appid=00000&click_id=00000&app_type=android&advertiser_id=0000 不能用特定的参数名称(×)

接收点击接口格式( Feedback URL )介绍

  • 请求方:腾讯广告点击后台
  • 处理方:广告主后台
  • 请求协议:http
  • 请求方式:GET

feedback URL示例:

http://www.example.com/gdt.cgi

接收点击接口示例:

http://www.example.com/gdt.cgi?muid={muid}&click_time={click_time}&appid={appid}&click_id={click_id}&app_type={app_type}&advertiser_id={advertiser_id}

实例如下:

Android应用:

http://www.example.com/gdt.cgi?muid=40c7084b4845eebce9d07b8a18a055fc&click_time=1406276499&appid=000000&click_id=007210548a030059ccdfd1d4&app_type=android&advertiser_id=20000

iOS应用:

http://www.example.com/gdt.cgi?muid=40c7084b4845eebce9d07b8a18a055fc&click_time=1406276499&appid=000000&click_id=007210548a030059ccdfd1d4&app_type=ios&advertiser_id=20000

接受点击接口参数介绍

名称 类型 描述
muid string 设备id,由IMEI(Android应用)md5生成,或是由IDFA(iOS应用)md5生成;
click_time int 点击发生的时间,由腾讯广告系统生成,取值为标准时间戳,秒级别
click_id string 腾讯广告后台生成的点击id,腾讯广告系统中标识用户每次点击生成的唯一标识
appid string Android应用ID为应用宝appid,iOS应用ID为Apple App Store的id
advertiser_id int64 广告主在腾讯广告(e.qq.com)的账户id
app_type string app类型;取值为 android或ios(联盟Android为unionandroid);注意是小写;根据广告主在腾讯广告(e.qq.com)创建转化时提交的基本信息关联
android_id string 由android_idmd5生成,当设备id获取不到或匹配不上时,可以作为归因补充
ip string IP地址,不加密,当设备号获取不到或匹配不上时,可以作为归因补充
user_agent string urlencode,当设备号获取不到或匹配不上时,可以作为归因补充
campaign_id int64 推广计划id
adgroup_id int64 广告id
creative_id int64 创意id
agent_id int64 代理商id
deeplink_url string 应用直达链接
dest_url string 落地页链接
device_os_type string 设备系统,ios、android
click_sku_id string DPA商品id
process_time int 请求时间
product_type int 商品类型
request_id string 请求id
site_set int 广告版位id
adgroup_name string 广告名称
oaid string 安卓系统移动终端补充设备标识
impression_id string 腾讯广告后台生成的曝光id,腾讯广告系统中标识用户每次曝光生成的唯一标识

设备标示取值和加密方案说明:

IMEI取值和加密说明:

  1. 描述

    • Android版本 < 6.0,只需要READ_PHONE_STATE静态权限(安装App时即可获取到该权限),即可通过系统API TelephonyManager#getDeviceId API获取准确值;
    • 6.0 <= Android版本 <= 9.0,READ_PHONE_STATE升级为动态权限,安装App时不会获得该权限,需要在App运行时用户在弹窗确认授权后才可以获取;
    • Android版本 >= 10.0,设备不可变ID的隐私保护得到进一步升级,一般App无法获取到IMEI。
  2. 原始数据获取

    TelephonyManager tm = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE); 
    deviceId = tm.getDeviceId(); 

    需要注意,android版本>=10不获取

  3. 加密方式

对MEI设备号转成小写,再进行md5编码,再小写,32位 md5(imei.toLowerCase()).toLowerCase()

  1. 测试用例

原始IMEI码:868049039501257

加密之后:8d3ebd3654fb46a2832296669cf1b536

IDFA取值和加密说明:

  1. 描述

IDFA是目前iOS系统主流的广告获取设备标识符方式,用户可开启、关闭,每次切换会改变为新的取值。 10以下的版本关闭时也能取到唯一值, >=10的iOS版本关闭时取到的值为00000000000 ;系统大版本升级(如11 到 12) 时,IDFA也会发生变化。

  1. 原始数据获取

    idfa = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
  2. 加密方式

IDFA 设备号保持大写,进行 md5 编码,再小写,32位;md5(idfa.toUpperCase()).toLowerCase()

  1. 测试用例

原始 IDFA 码:1E2DFA89-496A-47FD-9941-DF1FC4E6484A

加密之后:40c7084b4845eebce9d07b8a18a055fc

Muid(包括IMEI和IDFA)加密代码示例(C++):

bool GenerateMuid(const std::string& uni_id, const int32_t app_type, std::string* muid) 
{ 
    if (muid == NULL || uni_id.empty()) { 
        return false; 
    } 
    muid->clear(); 
    std::string tmp;  
    if (app_type == kAppTypeAndoirdImei) {
        LatinToLower(uni_id, &tmp); 
    }  
    else if (app_type == kAppTypeiOSIfa) { 
        LatinToUpper(uni_id, &tmp); 
    }  
    else { 
        return false; 
    }
    md5sum32l(tmp, muid);    // 32bit lower 
    return true; 
}

Android_id取值和加密说明:

  1. 描述

    • Android版本 < 8.0,不需要任何权限即可使用系统API(Settings.System.getString(getContentResolver(), Settings.System.ANDROID_ID))获取准确值
    • Android版本 >= 8.0,应用签名、用户(即系统上的用户账号)和设备的每个组合都具有唯一的 ANDROID_ID值,即使系统升级也不变。
  2. 原始数据获取

    Settings.System.getString(context.getApplicationContext().getContentResolver(); 
    Settings.System.ANDROID_ID); 
  3. 加密方式

对 android_id 进行 md5 编码,再小写md5(androidId).toLowerCase()

  1. 测试用例

原值:f40c5cf5100f9be3

加密后:1995c8f7cec20632797539b68555752f

OAID取值和加密说明:

移动安全联盟提出的安卓系统移动终端设备补充标识(OAID),保留原始值,不需要MD5编码。具体OAID介绍以及最新覆盖厂商范围请详见MSA官网。网站链接:http://msalliance.icoc.bz/col.jsp?id=120

接收点击接口响应信息

  • 响应格式:Json数据格式
  • 响应内容:{ret: 返回码, msg: 错误提示}
  • 返回码:返回码为0标识正常接收,其他返回码标识错误

    注意:返回值必须有『ret』,且参数值必须为0;否则视为不成功;返回值不能包含『302』
    返回值中的『错误信息』如果是中文,必须使用UTF-8字符集,不能使用GBK等其他字符集。