付费ios10.0.3

爱奇艺移动APP广告oCPX转化数据API联调对接文档目录一、概述.
3二、事件定义.
3三、应用API回传方案一(精确回传)41.
方案说明.
42.
接口一说明.
43.
接口二说明.
6四、应用API回传方案二(模糊回传)81.
方案描述.
82.
流程说明.
93.
固定接口说明.
9五、双目标联调.
11六、常见问题.
16七、附录一(接口一参数说明)18八、附录二(接口二参数说明)22九、附录三(URL编解码规则说明)22十、联系我们.
23更新点更新详情更新时间更新者应用API支持激活首日付费、激活-首日roi双目标投放主要涉及【接口二说明】模块里callback回调里付费金额回传调整,同时请关注QA说明2020.
12.
29秦学良一、概述激活数、注册数和付费数(付费金额)、次留是APP广告主衡量转化效果的一些重要指标.
为满足爱奇艺广告主对广告效果的监测需求,本文档介绍如何把从爱奇艺广告渠道分发的APP激活数、注册数或付费数回传给爱奇艺广告平台,帮助广告主跟踪转化效果.
对于回调了激活、注册或付费数据的广告,爱奇艺支持oCPC(目标激活成本出价、目标注册成本出价和目标付费成本出价)竞价方式,帮助优化转化.
回调方案适用于Android和iOS.
回调仅支持激活数、注册数和付费数三种转化目标.
二、事件定义1.
广告点击当爱奇艺用户点击广告素材(包括且不限于标题、按钮、图片、视频)时,触发点击事件,该事件被认为是次有效的广告点击.
进指定落地页后点击内部相关链接等为,不算为点击.
2.
应用激活当用户从爱奇艺客户端点击应用广告,并安装该应用后首次打开.
3.
应用注册当用户从爱奇艺客户端点击应用广告,完成激活并完成注册.
4.
应用付费当用户从爱奇艺客户端点击应用广告,完成激活注册,并产生付费.
三、应用API回传方案一(精确回传)1.
方案说明爱奇艺通过接口一将点击数据传送至广告主/第三方监测平台.
收到转化数据后,广告主/第三方需要根据用户的信息(如用户的idfa、imei等),匹配缓存的点击监测数据,并通过接口二将转化数据传回爱奇艺.
以爱奇艺用户为例:1)爱奇艺用户点击广告,爱奇艺客户端收集用户的点击事件.
2)爱奇艺客户端把点击事件发送给爱奇艺广告服务器.
3)爱奇艺广告服务器向广告监测服务(可由广告主自行开发,或托管给第三方监测平台)发送点击监测(接口一).
4)爱奇艺通过接口一将点击数据传送至广告主/第三方监测平台.
收到转化数据后,广告主/第三方需要根据用户的信息(如用户的idfa、imei等),匹配缓存的点击监测数据,并通过接口二将转化数据传回爱奇艺.
5)将匹配成功的激活、注册或付费信息第一时间回调给爱奇艺:回调方案callback_url,具体接口见下方"接口二".
6)爱奇艺将回调的激活、注册或付费数据与广告匹配.
7)在投放后台披露激活、注册或付费数据2.
相关逻辑1)数据流示意图(以激活为例)2)对应操作界面示意图3.
接口一说明接口一可以帮助广告主/第三方接收爱奇艺广告服务器供的广告点击信息.
1)简介:请求方:爱奇艺广告服务器.
处理方:广告主/第三方提供的监测平台服务器.
请求协议:HTTP协议/HTTPS协议.
请求地址:即点击监测地址,在爱奇艺投放平台填写的监测URL.
监测URL中,使双下滑线__参数__的形式来设置所需返回的数据.
2)具体示例如下:iOS示例:http://xxxx.
xxx.
comidfa=__IDFA__&oaid=__OAID__&mac=__MAC__&os=__OS__×tamp=__TS__&callback_url=__CALLBACK_URL__安卓示例:http://xxxx.
xxx.
comimei=__IMEI__&oaid=__OAID__&mac=__MAC__&androidid=__ANDROIDID__&os=__OS__×tamp=__TS__&callback_url=__CALLBACK_URL__*参数说明见附录一3)响应方式JSON数据格式4)响应内容不要求对方返回具体内容,使用http的状态码表示是否成功,返回状态码为200表示成功.
注:参数必须全大写,否则会替换失败;httpcode必须是200,才能进行联调.
有301,302跳转情况会导致请求失败,有可能会出现在http跳转https过程中.
托管给第三方监测平台的情况下,第三方监测平台对于参数的命名不一定和附录参数定义完全一致,但是含义及用途必须完全符合上述定义;监测链接大小不得超过10K;爱奇艺对监测域名没有限制,但是监测地址必须可以正常访问,不能有任何http的报错;监测链接不能是下载链接;监测链接内不能含有event_type参数,此参数需要在接口二阶段增加.
4.
接口二说明接口二用于广告主/第三方将激活、注册或付费上报给爱奇艺广告服务器,爱奇艺会将激活、注册或付费与广告关联,跟踪每个广告的转化效果.
对回调了激活、注册或付费数据的广告,爱奇艺支持oCP(目标转化出价)的竞价方式.
广告主/第三方必须在收到APP的激活、注册或付费后实时将效果上报给爱奇艺服务器,以免出现统计无效的情况.
1)callback_url回调点击监测链接(接口一)填写callback_url=__CALLBACK_URL__在广告产生点击时,爱奇艺通过接口一的参数callback_url=__CALLBACK_URL__将回调地址发送给点击监测链接对应的服务器,此URL使用urlencode进行编码.
广告主/监测平台收到对应用户的激活、注册或付费信息后,需对URL进行urldecode解码.
然后将callback_url发送回爱奇艺,回调激活、注册或付费信息.
对于付费类的转化目标(付费、首日付费、首日roi)或者有付费信息回传的需要(建议收到付费信息即回传,不需要去重,以便优化投放效果),监测平台需要解析并替换callback里的PAYMENT_AMOUNT宏(即付费金额信息),单位分,保留整数.
callback示例,dsp_conversion_cbck=cca3e1db647284c4469b0b0b91441947651&c=a3e1db647284c4469b0b0b9144194765&d=63002021674&f=311aeb9f76cf10de&b=1617271996&pmao=__PAYMENT_AMOUNT__&cst=__CONVERSION_TIME__&s=7b6798e89994056e89c1797e6a52700c&tpt=1&assistReportMatched=&adid=63002021674回调时请务必添加event_type参数到链接尾部,用以区别数据属于激活、注册或付费(注意:如不添加,则默认回调的数据为"激活"数据).
*参数说明见附录二*编解码规则说明见附录三2)响应格式:JSON数据格式3)响应内容:返回状态码为200表示成功.
具体的状态码以及对应的释义如下表:状态码信息释义建议200{"status":200,"message":"impression_id"}success记录此类型的数量,方便排查问题200{"status":200,"message":"missingevent_type.
"}成功,但缺少event_type的callback补齐event_type参数801{"status":801,"message":"parametererror:invalidtimestamp.
"}非正常时间戳请根据释义自查,此问题为广告主/第三方内部逻辑问题802{"status":802,"message":"parametererror:invalidevent_type,shouldbe0,1,2.
"}对应请求中event_type字段非0,1,2804{"status":804,"message":"parametererror:invalidsecuritycode.
"}校验不通过805{"status":805,"message":"parametererror:missingsecuritycode.
"}缺少校验码806{"status":806,"message":"parametererror:missingimpresssionid.
"}缺少曝光ID811{"status":811,"message":"expired.
"}转化离点击时间太长82x{"status":82x,"message":"internalerror.
"}其他错误请重试发送,若多次重试依旧返回此状态码,请联系爱奇艺人员反馈注:广告主需支持自动回传callback_url的能力,爱奇艺方不接受手动回传的方式;不推荐广告主回传转化目标为激活的callback_url时,尾部不添加对应的event_type参数;广告主可以在回传目标转化的URL之外,再多回传其他转化目标(仅限目前支持的转化目标)的URL并携带上与其对应的event_type参数,可以促使模型找到更精准的用户,降低转化成本.
例如:转化目标为激活,可以在回传激活的callback_url之外,再回传注册或者付费的callback_url+event_type.
但转化数依旧只采用激活数据.
callback_url的域名http://tc.
cupid.
iqiyi.
com/.
四、应用API回传方案二(模糊回传)1.
方案描述1)背景:投放过程中,有部分用户设备由于种种原因无法获取硬件设备等信息,同时由于AndroidQ系统版本发布后无法获取设备信息的情况越来越严重,这将导致无法精确回传,容易造成数据GAP,不利于客户的跑量速度和成本控制.
2)适用场景模糊回传方案,即为解决无法通过设备信息匹配造成数据GAP的解决方案,由于造成无法匹配的原因多种多样,建议客户同时使用精确回传和模糊回传方案,保证转化数据100%能够回传使用逻辑:优先使用精确回传方案,对于精确无法匹配的使用模糊回传方案.
使用方法:广告主/第三方使用爱奇艺提供固定API接口按照规定的格式将转化数据回传至爱奇艺,爱奇艺用于模型训练和报表展示.
2.
流程说明以爱奇艺用户为例:1)爱奇艺用户点击广告,爱奇艺客户端收集用户的点击事件.
2)爱奇艺客户端把点击事件发送给爱奇艺广告服务器.
3)当广告主/第三方监测平台接收到来自于爱奇艺的转化数据后,收集其他参数参数包括,广告主ID、用户IP、平台(ios、android)、激活时间、转化类型、渠道包等参数,回调爱奇艺固定接口.
4)爱奇艺将回调的激活、注册或付费数据与广告模糊匹配.
5)在投放后台披露激活、注册或付费数据3.
固定接口说明1)数据回传接口:http://tc.
cupid.
iqiyi.
com/dsp_conversion_cb/special2)回传方式:httpget3)参数:URL参数名类型参数参数取值是否备注含义必须aiint64广告主id是euint32用户ipIp转换为uint32是pfint32平台信息ios=32;安卓=33是etint32激活时间秒级时间戳是event_typeint32转化类型0:active激活1:register注册2:pay付费3:Retention次日留存210:授信(目前仅支持双目标中作为深度转化目标)4:加桌5:成功唤醒6:有效播放7:进群8:首日付费9:首次付费(仅限于sdk使用)是标记转化类型,如果缺失默认为激活11:首日roicpstring渠道包否尚未启用4)返回结果返回结果状态码Message含义原因{"status":200,"message":"68db36d8b895046f4b34bf4eded2b1de"}200上报id成功上报{"status":821,"message":"internalerror.
"}821未匹配到上报串服务内部未匹配到结果{"status":807,"message":"parametererror:invalidxxx.
"}807xxx参数无效参数类型错误{"status":807,"message":"parametererror:noxxx.
"}807没有xxx参数缺少参数五、双目标联调1.
应用双目标联调应用双目标联调是爱奇艺为有需求的客户提供的平衡深度转化成本和跑量的解决方案,解决客户投"激活"而付费效果不理想,投"付费"而跑量困难的问题.
双目标投放支持如下:转化目标深度转化目标激活付费激活注册激活次留激活授信激活首日付费激活首日roi唤醒成功付费注册次留注册授信双联调流程如下:1)第一步:新建联调勾选单目标:联调与之前应用api一致.
勾选双目标进行双目标联调:2)第二步、第三步与应用API之前联调一致,不发生变化.
3)第四步:针对双目标联调,该阶段与单目标联调一致,详情如下:4)第四步,收到转化:5)第五步,点击下一步,进入深度转化目标联调联调通过:2,单目标切换位双目标流程如下:已经联调通过的单目标联调单,点击再次联调,进入再次联调界面:再次联调界面如下:点击双目标显示深度转化目标:点击开始联调后进入双目标联调流程,同双目标联调二、三、四、五步.
注:单目标的转化目标为非激活的状态下不能更改为双目标3,其他逻辑1)双目标联调单不能切换为单目标2)双目标联调过程中先判断转化目标后判断深度转化目标3)转化联调通过即可进行单目标联调类型投放,待双目标联调通过后可进行双目标联调类型投放.
4)联调状态变为待联调、深度转化待联调、联调通过5)只有转化目标以及深度转化目标都通过后,同样的双目标联调直接通过,否则都要重新进行联调.
六、常见问题案例1:后台报参数拼写不正确http://g.
cn.
miaozhen.
com/x/k=2011467&p=6wit2&dx=0&rt=2&ns=__IP__&ni=__IESID&v=__LOC__&nd=__DRA__&np=__POS__&nn=__APP__&o=原因:参数不是文档中支持的标准参数.
解决方案:按照文档中标准参数填写或删除报错参数(报参数拼写错误,但广告仍然可以交且不影响展示和点击总数).
案例2:监测链接超过10K解决方案:修改链接大小.
建议链接最好使用直链,跳转链接很容易超过10K.
案例3:监测链接无法访问http://www.
tdxxxxxxxo.
com原因:后台会请求监测链接,如果监测链接无法访问会报错.
解决方案:确保监测链接可以正常访问.
案例4:激活、注册和付费有什么区别答:在接口二的链接中我们新增字段"event_type",用于区分应用下载的转化是激活、注册或付费.
当回传的字段event_type=0时,代表ative激活;当回传的字段event_type=1时,代表register注册;当回传的字段event_type=2时,代表pay付费.
案例5激活回传的时间需要客户/第三方那边实时回传,延迟回传会导致预估不准.
案例6:如果广告主自制监测链接,推荐使用的匹配字段(归因顺序)由于目前存在IDFA/IMEI获取失败的情况,建议您按照以下多种字段进行匹配(即,当IMEI匹配失败时,可采用AndroidID;AndroidID匹配失败时,采用ip+ua…以此类推),来高归因的成功率.
iOS:①idfa②ip+ua③macAndroid:①imei②AndroidID③ip+ua④mac案例7:联调一直卡在第三步下图进度上.
1)等一段时间,广告主/第三方上报数据可能有延迟.
2)看一下转化的目标和对方上报的事件是否匹配(目标是激活,需要对方上报激活事件;目标是注册,需要对方上报注册事件.
通过接口二中的event_type参数标识,见文档)3)确认urldecode处理是否符合规范(规范见附录三).
并核对urldecode结果是否正确.
4)以上还不能解决:将爱奇艺发送给广告主/第三方的点击监测链接,反馈给广告主/第三方.
让其确认三件事.
a)是否收到爱奇艺发送给他的点击监测链接.
b)爱奇艺发过去的监测链接有用户的imei/idfa,让广告主/第三方确认一下,这个用户是否激活,并匹配到爱奇艺的点击.
c)匹配到爱奇艺的点击,是否回调了爱奇艺激活接口,回调了,将回调的链接贴给爱奇艺.
可以给排查.
案例7:首日roi一次点击发送多次付费时,都需要回传吗转化数如何统计都需要回传,平台会将激活当天的付费记录为有效付费,有效付费会用于计算roi进而进行成本控制;超过当天的付费仍然可以作为算法模型训练数据,且不影响成本控制,因此建议回传.
一次点击发送多次有效付费当前会记录为多次转化,近期会调整为进行转化数去重,即一次点击最多会记录一次转化案例8:首日roi回传付费时是否可以在callback链接后直接拼接付费金额宏不可以,在callback链接后拼接会出现付费金额重复而无法解析的问题,会导致双方付费金额产生gap,因此需要直接替换callback链接付费金额宏(PAYMENT_AMOUNT)七、附录一(接口一参数说明)参数描述格式是否必填IDFAiOS下的IDFA,原文带"-",明文例如:458BE47D-7205-4010-BC77-DC6E551EC514iOS建议填写OPENUDIDiOS下的OpenUDID,原始值.
40位十六进制数字.
例如:0d943976b24c85900c764dd9f75ce054dc5986ff否IMEIAndroid下的IMEI,IMEI进行MD5例如:e86607bc47b52dc939e71e9edfe09f55安卓建议填写OAIDMSA提供的匿名设备标识符是ANDROIDIDAndroid下的ANDROIDID,例如:否ANDROIDID进行MD5559728b2022fa3cd893605112f626359MACMAC地址转大写,去冒号,然后MD5例如:e3f5536a141811db40efd6400f1d0a4e否MAC1MAC地址转大写,保留冒号,然后MD5例如:f8c65f0f6ea5cbffb7cb97cd6fae683c否IP点击广告的设备IP信息150.
255.
177.
215否OS客户端操作系统的类型1位数字,取0~3.
0表示Android1表示iOS2表示WindowsPhone3表示其他1否TS客户端触发监测的时间.
UTC时间戳,1970年起的秒数(备注:客户端构造点击事件的时间,如果缺失,则使用当前时间)--否UDIDiOS下的UDID.
配置这个参数后,会按照优先级获取设备信息:IDFA—>OPENUDID—>MACidfa为00000000-0000-0000-0000-000000000000时,会认为是无效,改为传递openudid--否UA客户端上报数据时http的header中的user_agent.
会urlencode例如:QIYIVideo%2F9.
10.
0%20(iOS%3Bcom.
qiyi.
iphone%3BiOS12.
0.
1%3BiPhone10%2C3)%20Corejar否CALLBACK_URL激活回调地址在广告点击的时候爱奇艺通过callback_url=__CALLBACK_URL__将回调地址发送给点击监测链接对应的服务器,URL用urlencode编码.
是监测平台收到对应用户的激活信息后,向CALLBACK_URL发一个http请求,回调激活信息.
监测平台无需关心这个URL的构成和内容,URL对监测平台保持透明.
注意:如您选择的是注册或付费为转化目标,回调时请务必添加event_type参数到链接尾部,用以区别数据属于激活、注册或付费(注意:如不添加,则默认回调的数据为"激活"数据).
SIGN签名使用替换后的url+key进行md5生成签名.
注意!
!
!
该字段一定放到url的最后,作为最后一个参数备注:签名是为了接口反作弊使用,一般不推荐使用否ADVERTISER_ID账户ID例如:51200110321否ORDER_GROUP_ID广告系列ID例如:62000124821否ORDER_PLAN_ID广告ID例如:63000206121否CREATIVE_ID创意ID例如:64000276321否QYID爱奇艺内部ID注意:qyid字段取值EncodeUR,使用需要decode否IMPRESSS_ID广告曝光ID否CLOUD_IQID云端iqid(内广客户需求)否CELL_PHONE_MANUFACTURER手机品牌字段取值EncodeUR,使用需要decode否SUA在WKWebView中获取的标准UA字段取值EncodeUR,使用需要decode否SCREEN_RESOLUTION分辨率指的屏幕宽高比,例如:1920,1080否附SIGN生成方式:1)生成方式说明使用替换后的url(不包括最后的SIGN参数)+key进行MD5生成签名.
2)举例监测链接为:http://appfly.
com/send/idfa/idfa=__IDFA__&sign=__SIGN__用户的IDFA:0E210CC5-44EA-490C-B95D-67E45AE93D433)生成方式a)替换宏值并去除尾部的SIGN参数url='http://appfly.
com/send/idfa/idfa=0E210CC5-44EA-490C-B95D-67E45AE93D43'b)从爱奇艺转化追踪工具获取到这个广告的key='ffbba6e3-9edc-456d-8de2-bdffdbee22d7'c)url+key=http://appfly.
com/send/idfa/idfa=0E210CC5-44EA-490C-B95D-67E45AE93D43ffbba6e3-9edc-456d-8de2-bdffdbee22d7d)生成sign.
md5(url+key),取32位小写.
例子中的sign=e251bee398af339215aa0471bb9c2e43e)替换SIGN宏url='http://appfly.
com/send/idfa/idfa=0E210CC5-44EA-490C-B95D-67E45AE93D43&sign=e251bee398af339215aa0471bb9c2e43'八、附录二(接口二参数说明)参数描述格式是否必填signature激活请求的签名用于对回调的激活信息做加密.
生成方式与sign一样.
否event_type区分回传的信息0:active激活1:register注册2:pay付费3:Retention次日留存4:加桌5:成功唤醒6:有效播放7:进群8:首日付费9:首次付费(仅限于sdk使用)11:首日roi是九、附录三(URL编解码规则说明)1)编码规则a)与js的encodeURIComponent方法保持一致.
b)encodeURIComponent不编码字符有71个:0-9,a-z,A-Z).
c)可了解:http://www.
w3school.
com.
cn/jsref/jsref_encodeURIComponent.
asp2)解码规则a)与编码规则一致decodeURIComponent.
b)仅针对CALLBACK_URL进行decode,并且仅执行一次.
c)可了解:http://www.
w3school.
com.
cn/jsref/jsref_decodeURIComponent.
aspd)在谷歌浏览器(Chrome)开启开发工具(快捷键F12),在Console页面,输入:decodeURIComponent("爱奇艺传递callback_url"),进行核对.
e)或者搜索"站长工具decode",使用该工具的UrlDecode功能进行校验.
十、联系我们如有相关问题,请联系爱奇艺人员.