• 上报(其他上报自行处理)
  • 文档目的

    1. 本文档主要介绍了如何使用犀光科技 indep_ad 广告接口,对接犀光广告;
    2. 本文档主要供合作伙伴的 web 端的技术人员开发对接使用

    注意事项

    1. 必须有 app_id 才能使用该接口;
    2. 所有的请求参数均为字符串格式! 如: client_ip:"192.168.1.144"。
    3. 如果不使用犀光提供的详情页时,按此文档请求广告;使用犀光详情页时,可忽略此文档。列表页广告只参考 response 和前端展示部分即可

    request

    详情页广告对接的协议格式如下:

    协议 http/https+post
    url
    https://xiaojiding.com/HttpService/indep_ad
  • 请求参数
  • 参数 说明 是否必须 备注
    api_version
    固定为 1
    必填
    app_id
    用户 id,犀光提供给用户
    必填
    timestamp
    时间戳
    必填
    精确到 s
    ad_show_type
    广告展示位置
    必填
    固定为 1
    user_id
    用户 id
    必填
    ua
    user agent
    必填
    需要 encode 编码
    os
    操作系统
    必填
    安卓传 Android,iOS 传 iOS
    os_version
    操作系统版本
    必填
    传具体的版本
    make
    手机品牌
    必填
    例如 HUAWEI
    client_ip
    客户端 ip
    必填
    传用户的真实 ip
    model
    手机型号
    必填
    例如 HUAWEI Y600-U00
    density
    屏幕密度
    选填
    如不填,会使用默认值取广告
    ppi
    每英寸所有的像素
    选填
    如不填,会按默认值去取广告
    hv
    横竖屏
    选填
    0:未知,1:竖屏,2:横屏
    screen_width
    手机屏宽
    必填
    screen_height
    手机平高
    必填
    device_type
    设备类型
    必填
    手机:"PHONE";平板:"TABLET"
    api_level
    安卓系统 api 级别
    选填
    dip
    像素值
    选填
    language
    系统语言
    选填
    zh 代表中文,en 代表英文
    imei
    手机真实物理序列号
    必填
    android 必填,一串数字
    android_id
    Android 设备系统 id
    选填
    idfa
    苹果手机标识
    必填
    ios 必填
    idfv
    IOS 设备的 idfv 值
    必填
    ios 必填
    udid
    IOS 设备的 openuid
    选填
    sn
    手机序列号
    选填
    imsi
    设备 imsi 值
    选填
    oaid
    匿名设备标识符
    选填
    若无法拿到 imei 值,建议填写此值
    mac
    mac 地址(android)
    必填
    network_type
    用户网络类型
    必填
    2g,3g,4g,5g,wifi
    carrier
    运营商
    必填
    传获取到的原始值,46000,46002 移动 46001 联通,46003 电信
    coordinate_type
    GPS 坐标类型
    选填
    WGS84 为全球卫星定位坐标系,GCJ02 国家测绘局坐标系,BD09 为百度坐标系
    longitude
    GPS 坐标经度
    选填
    latitude
    GPS 坐标纬度
    选填
    timestamp
    GPS 时间戳信息
    选填
    lac
    基站位置区域码
    选填
    cellularid
    基站编码
    选填
    country
    国家英文缩写
    选填
    CHN 代表中国

    response

    1.ad_zk

    一 当返回的 json 中 type 为"ad_zk"时,返回广告字段如下:

    参数名称 说明 备注
    errno
    错误类型,如果出错显示具体的错误,方便调试
    log_id
    每次请求的标识
    message
    错误信息
    statusCode
    返回状态码
    data
    type
    广告类型
    ad_zk
    ad_height
    广告高度
    ad_width
    广告宽度
    id
    广告 id
    image_url
    广告图片 url
    title
    广告标题
    icon_url
    icon url
    下角标图片链接
    landing_url
    广告落地页地址
    imp_track_url
    广告曝光上报 url
    为数组,逐条上报
    org_url
    xxx
    可以忽视,不用处理

    2.ad_lm

    二 当返回的 json 中 type 为"ad_lm"时,返回广告字段如下:

    参数名称 说明 备注
    errno
    错误类型,如果出错显示具体的错误,方便调试
    log_id
    每次请求的标识
    message
    错误信息
    statusCode
    返回状态码
    data
    type
    广告类型
    ad_lm
    ad_height
    广告高度
    ad_width
    广告宽度
    id
    广告 id
    image_url
    广告图片 url
    title
    广告标题
    icon_url
    icon url
    下角标图片链接
    org_url
    该类型广告的链接
    处理跳转的时候,需在该 url 后拼接 is_trans=1
    imp_track_url
    广告曝光上报 url
    为数组,逐条上报
    landing_url
    xxx
    可以忽视,不用处理

    3.ad_adx

    三 当返回的 json 中 type 为"ad_adx"时,返回广告字段如下:

    参数名称 说明 备注
    errno
    错误类型,如果出错显示具体的错误,方便调试
    log_id
    每次请求的标识
    message
    错误信息
    statusCode
    返回状态码
    data
    type
    广告类型
    ad_adx
    ad_height
    广告高度
    ad_width
    广告宽度
    id
    广告 id
    image_url
    广告图片 url
    title
    广告标题
    icon_url
    icon url
    下角标图片链接
    landing_url
    广告落地页地址
    imp_track_url
    广告上报 url
    为数组,逐条上报
    click_track_url
    点击上报 url
    为数组,逐条上报
    Incentive_video
    激励视频相关字段,为 json 串
    激励视频特有参数,如果不是激励视频,请忽略

    Incentive_video 参数

    参数名称 说明 备注
    action_type
    广告点击交互类型, 1:跳转 2:应用下载
    字符串, 例如:"2"
    mimetype
    视频物料类型
    int 类型 2:HTML, 3:原生视频
    video_url
    激励视频 素材的链接地址
    激励视频特有字段,视频素材地址,可能是 html 代码、url 链接
    arrDownloadTrackUrl
    开始下载上报地址
    一维数组
    arrDownloadedTrackUrl
    下载完成上报地址
    一维数组
    arrInstallTrackUrl
    开始安装上报地址
    一维数组
    arrInstalledTrackUrl
    安装完成上报地址
    一维数组
    c_url
    激励视频 点击后落地页跳转地址
    激励视频特有字段,如果是 html 代码,需要使用 webview 对其渲染(如果是下载类的,c_url 一般是 apk 的下载地址;如果是非下载类的,c_url 一般是落地页点击跳转地址)
    video_ad_start
    激励视频播放开始上报
    一维数组,激励视频特有字段
    video_ad_25per
    激励视频播放 25%上报
    一维数组,激励视频特有字段
    video_ad_50per
    激励视频播放 50%上报
    一维数组,激励视频特有字段
    video_ad_75per
    激励视频播放 75%上报
    一维数组,激励视频特有字段
    video_ad_end
    激励视频自动播放完成的上报
    一维数组,非必须返回字段
    video_ad_close
    激励视频播放被关闭的上报
    一维数组,激励视频特有字段
    skip
    激励视频播放跳过
    一维数组,激励视频特有字段
    video_duration
    激励视频播放时长
    激励视频特有字段
    prefetch
    客户端是否预加载广告视频
    激励视频特有字段
    endcardhtml
    视频播放完成后显示的 endCard HTML 页面
    激励视频特有字段
    callbackTrackers
    服务器激励回调上报 URL
    一维数组,激励视频特有字段
    videoloaded
    广告加载成功追踪 URL
    一维数组,激励视频特有字段
    errortrackers
    播放视频错误追踪 url
    一维数组,激励视频特有字段
    unmute
    关闭静音播放事件上报 URL
    一维数组,激励视频特有字段
    mute
    静音播放上报 URL
    一维数组,激励视频特有字段
    land_notice
    落地页曝光时上报
    一维数组,非必须返回字段
    land_click
    落地页点击时上报
    一维数组,非必须返回字段
    land_close
    落地页关闭时上报
    一维数组,非必须返回字段

    4.ad_lmnew

    四 当返回的 json 中 type 为"ad_lmnew"时,返回广告字段如下:

    参数名称 说明 备注
    errno
    错误类型,如果出错显示具体的错误,方便调试
    log_id
    每次请求的标识
    message
    错误信息
    statusCode
    返回状态码
    data
    type
    广告类型
    ad_lmnew
    ad_height
    广告高度
    ad_width
    广告宽度
    id
    广告 id
    image_url
    广告图片 url
    title
    广告标题
    landing_url
    广告落地页地址
    lm_js_sdk_str
    js script 字符串
    为数组,需前端自己插入,lm_js_sdk_str[0]为广告 js 脚本,lm_js_sdk_str[1]若存在则为前者的 sdk
    imp_track_url
    广告上报 url
    为数组,逐条上报
    org_url
    xxx
    可以忽视,不用处理

    前端展示(HTML)

    1.ad_zk 类型

    前端自己布局 主要用到以下参数

    布局需要的参数

  • title - 广告标题
  • img_url - 广告素材图片 多张图片以英文逗号分隔 如"图片 1.jpg,图片 2.jpg,图片 3.jpg"
  • landing_url - 广告落地页地址
  • 上报需要的参数

  • imp_track_url 为数组,需要一一上报
  • 2.ad_adx 类型

    前端自己布局 主要用到以下参数

    布局需要的参数

  • title - 广告标题
  • img_url - 广告素材图片 多张图片以英文逗号分隔 如"图片 1.jpg,图片 2.jpg,图片 3.jpg"
  • landing_url - 广告落地页地址
  • 上报需要的参数

  • imp_track_url 为数组,需要一一上报
  • click_track_url 为数组,点击时需要一一上报
  • 3.ad_lm 类型

    主要用到以下参数

    布局需要的参数

  • org_url - 广告的链接 需要在后面拼接 '&is_trans=1'
  • ad_height - 广告高度
  • ad_width - 广告宽度
  • 上报需要的参数

  • imp_track_url 为数组,需要一一上报
  • <!--不能直接使用-->
    <iframe
      id="iframe"
      src="`${ org_url }&is_trans=1`"
      scrolling="no"
      frameborder="0"
      width="100%"
      height=""
    ></iframe>
    
    <script>
      const clientWidth = document.body.clientWidth
      const height = (ad_height / ad_width) * clientWidth
      function iframeHeight() {
        const obj = document.getElementById('iframe')
        obj.height = height
      }
      iframeHeight()
    </script>
    

    4.ad_lmnew 类型(原生 Andorid/IOS 无法用)

    主要用到以下参数

    生成dom元素需要的参数

  • lm_js_sdk_str - js script 字符串 数组 ['','']
  • -- lm_js_sdk_str[0] 广告的 script 标签字符串
  • -- lm_js_sdk_str[1] 若存在 则为 sdk script 标签字符串
  • 上报需要的参数

  • imp_track_url 为数组,需要一一上报
  • <!--放置广告的容器-->
    <div id="ad"></div>
    <!--js代码-->
    <script>
      /****** 以下两个方法可直接使用 *******/
      /************ start **************/
      function createScript(str) {
        const tempDom = document.createElement('div')
        tempDom.innerHTML = str
        const tem = tempDom.childNodes[0]
        const script = document.createElement('script')
        for (let i = 0; i < tem.attributes.length; i++) {
          const item = tem.attributes[i]
          script.setAttribute(item.name, item.value)
        }
        script.innerHTML = tem.innerHTML
        if (script.innerHTML.includes('document.write')) {
          const innerHTML =
            'var currentScript = document.currentScript;var d = document;' +
            '(function () {' +
            'var document = {' +
            'write: function (str) {' +
            'var div = d.createElement("div");' +
            'div.innerHTML = str;' +
            'for (var i = 0; i < div.childNodes.length; i++) {' +
            'currentScript.parentNode.insertBefore(div.childNodes[i], currentScript)}}};' +
            script.innerHTML +
            '})()'
          script.innerHTML = innerHTML
        }
        return script
      }
      const addedList = []
      function addSDK(sdkStr) {
        if (!addedList.includes(sdkStr)) {
          addedList.push(sdkStr)
          const script = createScript(sdkStr)
          document.body.appendChild(script)
        }
      }
      /************ end **************/
    
      if (lm_js_sdk_str[0]) {
        const script = createScript(lm_js_sdk_str[0])
        const container = document.getElementById('ad')
        container.appendChild(script)
        if (lm_js_sdk_str[1]) {
          addSDK(lm_js_sdk_str[1])
        }
      }
    </script>
    

    上报(其他上报自行处理)

    激励视频上报(type: ad_adx)

    当为激励视频需要特殊上报字段,如下(字段在 Incentive_video 中,ad_zk 和普通 ad_adx 广告无需考虑):

    1. 曝光:对应上报字段,imp_track_url,
    2. 点击:对应上报字段,click_track_url,在用户点击横幅广告时调用,并打开落地页 strLinkUrl
    3. 开始播放:对应上报字段,video_ad_start,调用时机:视频开始播放(包括跳出应用后返回继续播放)
    4. 跳过:对应上报字段,skip,调用时机,视频未完全播放完成
    5. 关闭:对应上报字段,ad_close,调用时机,视频关闭
    6. 播放结束:ad_end 字段,若有则上报,若无,或为空数组,不需上报
    7. 开始下载:arrDownloadTrackUrl 字段,若有则上报,若无,或为空数组,不需上报
    8. 下载完成:arrDownloadedTrakUrl 字段,若有则上报,若无,或为空数组,不需上报
    9. 开始安装:arrIntallTrackUrl 字段,若有则上报,若无,或为空数组,不需上报
    10. 安装完成:arrIntalledTrackUrl 字段,若有则上报,若无,或为空数组,不需上报
    11. 视频加载失败:errortrackers 字段,若有则上报,若无,或为空数组,不需上报
    12. 视频加载完成:videoloaded 字段,若有则上报,若无,或为空数组,不需上报
    13. 播放视频静音:mute 字段,若有则上报,若无,或为空数组,不需上报
    14. 播放视频非静音:unmute 字段,若有则上报,若无,或为空数组,不需上报
    15. 曝光落地页:land_notice 字段,若有则上报,若无,或为空数组,不需上报
    16. 点击落地页:land_click 字段,若有则上报,若无,或为空数组,不需上报
    17. 关闭落地页:land_close 字段,若有则上报,若无,或为空数组,不需上报

    *激励视频上报链接处理,替换宏值

    情况 1:

    是否包含 origin_time=%25%25origin_time%25%25,如果有,替换为事件的发生 unix 时间戳(毫秒), 例,origin_time=12536984622,也需要判断是否包含 time=%25%25time%25%25,如果有,替换为设备的当前的时间戳(毫秒) ,例, time=12536984622。 other_click_url 字段,开发者要判断是否包含 da_area=%25%25area%25%25,da_area=%25%25area%25%25 代表点击区域,目前只用 hot 替换, 例,da_area=hot video_ad_start 字段, 开发者要判断是否包含 da_ext1=%25%25play_mode%25%25,da_ext1=%25%25play_mode%25%25 代表播放方式 0:自动播放、 1:手动播放 ad_close 字段,开发者要判断是否包含 da_ext2=%25%25cur_time%25%25 和 da_ext4=%25%25start_time%25%25, da_ext2=%25%25cur_time%25%25 代表打印当前播放的进度(秒)、da_ext4=%25%25start_time%25%25 代表打印开始播放时的进度(秒) 上报参数里面有宏(__UNIXMILLI__)的,需要客户端替换成设备的当前的时间戳,单位是毫秒

    情况 2:

    用户点击坐标宏替换 在曝光上报、点击上报、落地页等 url 中,可能会有一些宏定义需要替换成相应的坐标参数。

    具体坐标宏对应如下:

    参数 类型 说明
    __ABZMX__
    int32
    相对与屏幕的(0,0)点坐标的点击位置(x,y); 代表点击触发 "x" 坐标的实际值
    __ABZMY__
    int32
    相对与屏幕的(0,0)点坐标的点击位置(x,y); 代表点击触发 "y" 坐标的实际值
    __ABZCX__
    int32
    相对与屏幕的(0,0)点坐标的点击位置(x,y); 代表点击结束 "x" 坐标的实际值
    __ABZCY__
    int32
    相对与屏幕的(0,0)点坐标的点击位置(x,y); 代表点击结束 "y" 坐标的实际值
    __EVENT_TIME_START__
    long
    事件触发的时间戳,单位毫秒,例如,展现上报,为当前时间戳,落地页与点击上报,为用户点击广告按下屏幕的时刻
    __EVENT_TIME_END__
    long
    事件结束的时间戳,单位毫秒, 例如,落地页与点击上报,为用户点击广告离开屏幕的时刻
    __VIDEO_DURATION__
    long
    仅在视频广告应答出现,点击视频时的播放时长,单位秒
    __CLICKID__
    long
    值来源于 action_type=4 时请求 clickurl 获取到的响应内容,用于追踪转化效果