开发文档

开发文档时对接过程中的指导规范。

广告对接文档
媒体对接文档

落地页用户转化对接JS&API

一、概述

(一)对接价值

广告主在推啊投放后,用户进入广告主落地页后会发生用户的转化行为,跟踪用户的这些后端数据,能够帮助广告主更好的优化广告效果。
推啊平台为广告主提供人机结合、oCPC 等智能投放策略,落地页用户转化的回收可实时用于投放策略调整,更好稳定投放,以最低的成本帮助广告主带来最大的回收。

(二)应用场景

当广告主考核广告投放效果的主要指标为以下这些指标时,可进行落地页的后端数据对接:
  • 填表/申请;
  • 下单;
  • 注册;
  • 领取;
  • 完件;
  • ...

(三)对接流程

1、请联系与您对接的销售;
2、推啊提供专业对接支持,配合广告主优化;
3、方案对接,联调;
4、测试及后续优化。

(四)基本名词介绍

1、曝光数据: 
  • PV,即页面浏览量,用户每 1 次对网站中的每个网页访问均被记录 1 次。用户对同一页面的多次访问,访问量累计;
  • UV,即访问页面的人数,根据 PV 去掉重复访问页面的用户数据。
2、落地页用户转化: 用户进入页面后,在落地页发生的转化行为,如点击,长按按钮,提交表单等。
3、常用参数含义: 
  • a_oId :唯一标识订单 id ,也称推啊ID;
  • advertkey :推啊广告秘钥,由推啊提供。

二、落地页用户行为转化对接

根据不同需求,有如下两种对接方式:

a.落地页JS对接——轻量快速,可直接采集落地页相关数据;

b.落地页API对接——稳定可靠,广告主可自主决定上传内容。

以下分别介绍落地页的 JS 和 API 的对接方式,广告主可选择其中一种完成对接。

(一)落地页 JS 对接

1、落地页数据回传原理图

2、JS 对接流程图

3、曝光事件转化(引入曝光代码)

在落地页页面的 head 标签中加入脚本:

<script type="text/javascript" src="//yun.tuisnake.com/h5-mami/log.js" id="send_log"></script>
                    

4、点击事件转化

广告主在按要求接入了 JS 后,广告主落地页在发生转化时,页面发生跳转,则转化请求会被中断,需要按以下方式进行跳转: 在转化发生时(提交或者注册成功时)调用 countLog.init(function,option) 方法,方法含有两个参数,参数可以为空:
  • function 是回调函数,需要将跳转行为通过回调函数执行,如 function(){转化行为};
  • option 是标记位,当出现多个转化埋点时使用,是一个 json 键值对,如{locationName:valueName}, 键值和数值都可以自定义,用来区别不同的转化。
                      
                          // 当落地页在发生转化时,页面发生跳转,那么转化请求就会被中断,需要将跳转行为通过回调函数执行,如function(){转化行为}。
                          function Transformation() {
                            /*
                           * 你的代码逻辑
                           */
                          countLog.init(function() {
                              window.location.href = 'http://www.tuia.cn';
                            });
                          }
                      
                    

如下图:

5、长按屏幕转化(非必选)

部分广告主的落地页,因为需要长按复制公众号信息, 所以需要统计屏幕长按转化数据,则在 DOM 元素上添加 data-setting-press 属性。例如:
  <div class="form-group bgbtn" data-setting-press="value">
                              <label class="control-label">长按转化</label>
                            </div>  
在长按元素上添加 data-setting-press 元素,用户按 800ms 会计算一次转化。

(二)落地页API对接

1. 对接url

2. 请求方式

请求方式为:get / post。

3. 传入参数字段

字段名字段类型注释是否必填注释
a_oIdString需 Encode推啊订单 ID,从落地页 URL 中截取
advertKeyString推啊广告秘钥联系 AE 获取
typeInt类型 :7:曝光;8:转化
a_timeStampString用户转化时间戳
ipString用户IP
osString系统iOS,Android
osVersionString需Encode操作系统版本号
modelString需Encode手机型号
uaString需Encode用户代理User-Agentheader中的
user-agent设置为标准格式;
参考格式:Mozilla/5.0 (Linux;
Android 6.0.1;
MI 4LTE Build/MMB29M;
wv) AppleWebKit/537.36 (KHTML, like Gecko)
Version/4.0 Chrome/51.0.2704.81 Mobile Safari/537.36
channelidString需EncodeAPP所属渠道号
brandString需Encode手机品牌
exString扩展字段JSON格式字符串
partnerKeyString合作key
signatureString签名
userNameString用户名
sexInt性别 1:男;2:女
phoneString用户手机号
ageInt用户年龄
areaString地区(省市区)
deviceString机器标识

4. 返回字段

字段名注释
redesc错误描述
record错误码
a_oid推啊订单ID

返回demo如下
{"redesc":"成功","record":"0000000","a_oId":"taw-123"}

{"redesc":"Required parama_oId Missing","record":"0110002"}

注意:只有在a_oId有效的情况下才会返回a_oId字段,测试情况或者a_oId无效时则不返回。

5. APP错误码解释

错误码描述
0000000成功
0110001必要参数不可为空
0110002a_oId缺失
0110007类型缺失

表单类广告主后端数据对接(JS)

一、概述

(一)对接价值

表单类广告投放后,除了关注用户在落地页的填表/申请,也需要关注后续完件、激活等情况;跟踪用户的这些后端数据,能够帮助广告主更好的优化广告效果。
推啊平台为广告主提供人机结合、oCPC 等智能投放策略,后端数据回收可实时用于投放策略调整,更好稳定投放,以最低的成本帮助广告主带来最大的回收。

(二)应用场景

当广告主考核广告投放效果的主要指标为以下这些指标时,可进行落地页的后端数据对接:
  • 填表/申请;
  • 下单;
  • 注册;
  • 领取;
  • 完件;
  • 签收;
  • ...

(三)对接流程

1、请联系与您对接的销售;
2、落地页对接(广告主自主提供)——根据落地页对接意向:
a.落地页JS对接——可直接采集落地页相关数据,需要广告主开发接入js;
b.落地页API对接——广告主开发获取落地页信息,并自主回传落地页信息;
3、推啊用户标识(a_oId)获取及关联、存储对接
4、广告主对接后端API回传用户后端行为
5、测试及后续优化,推啊提供对接文档及后续专业对接支持,配合广告主优化

(四)对接原理

用户点击广告-进入活动场景-点击相关活动券-进入广告主落地页-落地页转化-JS/API 上报转化数据-后续用户完成激活、付费等行为-采集并上报推啊ID(a_oId)及转化状态

说明: 每个落地页链接后带推啊 ID(a_oId) 作为落地页的唯一标识。

(五)基本名词介绍

1、曝光数据: 
  • PV,即页面浏览量,用户每 1 次对网站中的每个网页访问均被记录 1 次。用户对同一页面的多次访问,访问量累计;
  • UV,即访问页面的人数,根据 PV 去掉重复访问页面的用户数据。
2、落地页用户转化: 用户进入页面后,在落地页发生的转化行为,如点击,长按按钮,提交表单等
3、后续用户转化行为: 用户离开落地页后,在后续的产品链路中发生的转化行为,如进件,付费,激活APP等
4、常用参数含义: 
  • a_oId :唯一标识订单 id ,也称推啊ID
  • advertkey :推啊广告秘钥,由推啊提供

二、落地页用户行为转化对接

对接表单类后端转化,需广告主在落地页中自主获取a_old并做存储(暂不可使用推啊提供落地页),根据不同需求,有如下两种对接方式:

a.落地页JS对接——轻量快速,可直接采集落地页相关数据;

b.落地页API对接——稳定可靠,广告主可自主决定上传内容。

以下分别介绍落地页的 JS 和 API 的对接方式,广告主可选择其中一种完成对接。

(一)落地页 JS 对接

1、落地页数据回传原理图

2、JS 对接流程图

3、曝光事件转化(引入曝光代码)

在落地页页面的 head 标签中加入脚本:

<script type="text/javascript" src="//yun.tuisnake.com/h5-mami/log.js" id="send_log"></script>
                  

4、点击事件转化

广告主在按要求接入了 JS 后,广告主落地页在发生转化时,页面发生跳转,则转化请求会被中断,需要按以下方式进行跳转: 在转化发生时(提交或者注册成功时)调用 countLog.init(function,option) 方法,方法含有两个参数,参数可以为空:
  • function 是回调函数,需要将跳转行为通过回调函数执行,如 function(){转化行为};
  • option 是标记位,当出现多个转化埋点时使用,是一个 json 键值对,如{locationName:valueName}, 键值和数值都可以自定义,用来区别不同的转化。
                    
                        // 当落地页在发生转化时,页面发生跳转,那么转化请求就会被中断,需要将跳转行为通过回调函数执行,如function(){转化行为}。
                        function Transformation() {
                          /*
                         * 你的代码逻辑
                         */
                        countLog.init(function() {
                            window.location.href = 'http://www.tuia.cn';
                          });
                        }
                    
                  

如下图:

5、长按屏幕转化(非必选)

部分广告主的落地页,因为需要长按复制公众号信息, 所以需要统计屏幕长按转化数据,则在 DOM 元素上添加 data-setting-press 属性。例如:
                    
                        <div class="form-group bgbtn" data-setting-press="value">
                            <label class="control-label">长按转化</label>
                          </div>
                    
                  
在长按元素上添加 data-setting-press 元素,用户按 800ms 会计算一次转化。

(二)落地页API对接

1. 对接url

2. 请求方式

请求方式为:get / post

3. 传入参数字段

字段名字段类型注释是否必填注释
a_oIdString需 Encode推啊订单 ID,从落地页 URL 中截取
advertKeyString推啊广告秘钥联系 AE 获取
typeInt类型 :7:曝光;8:转化
ipString用户IP
osString系统iOS,Android
osVersionString需Encode操作系统版本号
modelString需Encode手机型号
brandString需Encode手机品牌
uaString需Encode用户代理User-Agentheader中的
user-agent设置为标准格式;
参考格式:Mozilla/5.0 (Linux;
Android 6.0.1;
MI 4LTE Build/MMB29M;
wv) AppleWebKit/537.36 (KHTML, like Gecko)
Version/4.0 Chrome/51.0.2704.81 Mobile Safari/537.36
channelidString需EncodeAPP所属渠道号
a_timeStampString用户转化时间戳
partnerKeyString合作key
signatureString签名
userNameString用户名
sexInt性别 1:男;2:女
phoneString用户手机号
ageInt用户年龄
areaString地区(省市区)
deviceString机器标识
exString扩展字段JSON格式字符串

4. 返回字段

字段名注释
redesc错误描述
record错误码
a_oid推啊订单ID

返回demo如下
{"redesc":"成功","record":"0000000","a_oId":"taw-123"}

{"redesc":"Required parama_oId Missing","record":"0110002"}

注意:只有在a_oId有效的情况下才会返回a_oId字段,测试情况或者a_oId无效时则不返回。

5. APP错误码解释

错误码描述
0000000成功
0110001必要参数不可为空
0110002a_oId缺失
0110007类型缺失

三、推啊用户标识获取及关联

在落地页转化的用户,在离开落地页后也会有后续的转化行为。

如需对后续行为进行追踪,需广告主记录推啊 ID (a_oId),并根据标识与用户关联。

(一) 推啊 a_old 获取

在完成落地页对接后,需从推啊投放url中截取推啊 ID (a_oId), 需在落地页内单独引入:

location.search.replace(/^\?/, '') + location.hash.replace(/^\#/, '&')

注:每个推啊投放链接中会拼接推啊的唯一用户识别编码

(二) 推啊 a_old 用户信息关联

在获取 (a_oId) 后,需将其与用户的唯一标示信息做关联。如

  • 手机号
  • 身份证号
  • 账户名

将推啊 ID 及获取的唯一标识一同存储在服务器中,以便后续转化时检索调用

四、后续用户行为转化对接

(一)流程说明

用户在落地页发生转化时,此时记录用户的转化行为及关联用户的推啊 ID(a_oId) ,并在服务器做存储

当用户离开落地页,发生后续的转化行为时:

1、根据用户的标识在已存储的用户中查询用户对应的推啊 ID

2、通过推啊的 API 接口将用户推啊 ID 及转化行为回传至推啊

(二) API 方式数据回传原理图

(三) API对接流程图

(四) 后续用户转化信息回传(API)

1. 对接url

2. 请求方式

请求方式为:get / post

3. 传入参数字段

字段名字段类型注释是否必填注释
a_oIdString需 Encode推啊订单 ID,从落地页 URL 中截取
advertKeyString推啊广告秘钥联系 AE 获取
subTypeInt1:安装APP;
2:启动APP;
3:注册账号;
4:激活账号;
5:登录账号;
6:用户付费;
7:用户进件;
8:用户完件;
9:用户签收;
10:用户拒收;
只回传需要查看的行为对应的参数
1 安装 APP:下载完成 APP
2 启动 APP:首次打开 APP
ipString用户IP
osString系统iOS,Android
osVersionString需Encode操作系统版本号
modelString需Encode手机型号
uaString需Encode用户代理User-Agentheader中的
user-agent设置为标准格式;
参考格式:Mozilla/5.0 (Linux;
Android 6.0.1;
MI 4LTE Build/MMB29M;
wv) AppleWebKit/537.36 (KHTML, like Gecko)
Version/4.0 Chrome/51.0.2704.81 Mobile Safari/537.36
channelidString需EncodeAPP所属渠道号
brandString需Encode手机品牌
exString扩展字段JSON格式字符串
a_timeStampString用户转化时间戳
partnerKeyString合作key
signatureString签名
userNameString用户名
sexInt性别 1:男;2:女
phoneString用户手机号
ageInt用户年龄
areaString地区(省市区)
deviceString机器标识

4. 返回字段

字段名注释
redesc错误描述
record错误码
a_oid推啊订单ID

返回demo如下
{"redesc":"成功","record":"0000000","a_oId":"taw-123"}

{"redesc":"Required parama_oId Missing","record":"0110002"}

注意:只有在a_oId有效的情况下才会返回a_oId字段,测试情况或者a_oId无效时则不返回。

5. APP错误码解释

错误码描述
0000000成功
0110001必要参数不可为空
0110002a_oId缺失
0110007类型缺失