Media API

背景

对有APP流量变现需求但由于各种原因无法嵌入极光联盟SDK的开发者，极光联盟提供基于Media API的合作方式供开发将流量以API形式接入极光联盟。开发者应保证获得用户授权同意，由开发者收集并向极光提供如下字段。本文档详细介绍了Media API的运营对接流程和接口协议等内容。

对接流程

接收API邀请： 极光联盟API采用邀请制加入，开发者接收邀请后，可在运营人员指导下提交API接入请求；

开通API权限： API权限基于应用授权，应用授权后方可为应用创建API广告位；API权限基于应用授权，获得APP secret。应用授权后方可为应用创建API广告位；

广告 API

极光联盟广告API提供请求广告和数据上报接口。极光联盟支持两种方式请求广告，强烈建议采用第一种方式1请求，开发者一方面具有更大可控制性，另一方面可以防止极光联盟分配的app secret泄露：

1. 开发者通过自己服务器后台请求极光联盟广告API
2. 开发者APP直接请求极光联盟广告API

广告请求

功能描述

通过此接口请求广告

接口地址：https://union-api.ad.jiguang.cn/v1/ads

示例：

          
curl -X POST \

  https://union-api.ad.jiguang.cn/v1/ads \

  -H 'Content-Type: application/json' \

  -d '{

    "device": {

        "os": "android",

        "os_version": "1.2.3",

        "model": "oppo v20",

        "manufacturer": "oppo",

        "imei": "868179044195447"

    },

    "network": {

        "ip": "119.139.196.49"

    },

    "slot": {

        "id": "api测试",

        "width": 100,

        "height": 100

    },

    "app": {

        "app_key": "571b65723a5fa6c96d755f9e",

        "app_bundle_id": "abc.test"

    },

    "timestamp": 1645067885,

    "nonce": "123456",

    "sign": "61cbd53c7026e99332bf6964264d3948",

    "version": "1.0"

}'

        

请求方式

HTTP POST请求

注意： 请求体是JSON字符串。请求头Content-Type请设置为application/json。

请求参数

原则： 在取值正确情况下，尽量填写相关请求参数，如果不能保证取值正确性，这种情况下不填写，否则会影响变现效果。

device参数结构：

注意：

1. 对安卓设备请求，imei、imei_md5、oaid至少要填写其中一个
2. 对ios设备请求，idfa、idfa_md5至少要填写其中一个

network参数结构：

app参数结构：

geo参数结构：

slot参数结构：

广告响应

注意： 该接口会返回多条广告，但开发者应该只选择一条广告进行曝光展示，其余广告应丢弃

曝光上报

开发者APP曝光广告时候，需要调用此接口上报曝光信息，必须由客户端曝光，不能通过服务端调用此接口，且禁止做任何改动。

曝光有效性标准如下：

广告展示区域的50%以上像素点在用户屏幕上并且持续可见时间超过1秒钟。

接口地址

https://union-api.ad.jiguang.cn/v1/event/impression

该接口地址为广告请求接口返回的impression_url字段

示例：

https://union-api.ad.jiguang.cn/v1/event/impression?d=N2Y3ZTc2ZTM0ZWRhMDIw&n=DZL6oJ&t=1643078474

请求方式

HTTP GET请求

响应参数

点击上报

当用户点击广告时候，开发者需要调用点击上报接口来上报给极光联盟。

接口地址

https://union-api.ad.jiguang.cn/v1/event/click

该接口地址为广告请求接口返回的click_url字段

示例： https://union-api.ad.jiguang.cn/v1/event/click?d=OWJlMDhkYjJkMTRjMjgzNzMyYzR&dx=__DOWN_X__&dy=__DOWN_Y__&he=__HEIGHT__&n=IYvano&rh=__REQ_HEIGHT__&rw=__REQ_WIDTH__&t=1644501941&ux=__UP_X__&uy=__UP_Y__&wi=__WIDTH__

该接口同曝光接口一样，必须要由开发者APP调用，不能通过服务端调用此接口。开发者在广告点击时需要捕获用户点击坐标，该值将在联盟后台用来帮助提升用户点击率，从而提高开发者收入。坐标均指相对于实际广告位左上角的坐标，如下图所示，箭头方向为正坐标方向，坐标单位为像素。如无法获取坐标时，请替换为-999。

该接口中，预填充了一些占位参数，开发者需要使用捕获到的坐标等替换掉这些占位参数。占位参数列表如下：

请求方式

HTTP GET请求

响应参数

转化上报

• 对于APK下载类型广告，广告联盟需要追踪下载效果，包括下载开始率、下载完成率和安装率，所以需要APP上报下载开始、下载完成和安装完成。
• 对于拉活广告，极光联盟需要追踪应用直达效果，包括尝试唤起APP率和唤起APP成功率，所以需要APP上报应用直达广告尝试唤起APP和应用直达广告唤起APP成功。
• 对于APP场景下的应用直达类型广告，联盟还需要追踪APP应用安装率（应用已安装/应用未安装/无法获取应用安装信息），所以还需要APP上报应用已安装/应用未安装/无法获取应用安装信息。

接口地址

https://union-api.ad.jiguang.cn/v1/event/conversion

该接口地址为广告请求接口返回的conversion_url字段。

示例：https://union-api.ad.jiguang.cn/v1/event/conversion?ai=__ACTION_ID__&d=M2MxNDY4ZmIwMTgxYmRmYz&n=4lHVeL&t=1643078474

该接口中，预填充了占位参数，开发者需要根据具体业务逻辑替换掉占位参数。占位参数列表如下：

请求方式

HTTP GET请求

响应参数

竞价上报

• 对于开通了实时竞价的API流量，广告联盟需要回收竞胜情况
• 开发者在收到联盟广告价格完成比价后，必须实时、直接通过竞价上报链接上报竞价结果及相关信息

竞价上报流程

接口地址

https://example.com/api/v1/event/bidNotice

该接口地址为广告请求接口返回的bid_notice_url字段

示例：http://172.17.9.211:9050/v1/event/bidNotice?ai=__ACTION_ID__&wbp=__WIN_BID_PRICE__&n=4lHVeL&t=1643078474

该接口中，预填充了占位参数，开发者需要根据具体业务逻辑替换掉占位参数。占位参数列表如下：

附录

错误码

签名生成方法

开发者在极光联盟后台创建应用时，系统会为开发者分配一个Appkey和App secret(可在应用编辑页面查看)。其中Appkey使用识别开发者身份，App secret用来进行生成签名认证。

当开发者请求广告时候，请传递正确的签名，否则极光联盟后台会将此次请求当做非法请求。签名参数sign生成方法如下：

sign = md5(md5(App_secret) + slot.id + nonce + timestamp)

注意： 接口中MD5加密之后要求是32位，且小写，如果大写，请转换成小写

极光联盟广告样式

开发者根据创意要素中相应字段进行渲染处理

极光联盟联调使用广告位

app_key： 51a694d7e13b78b9aad72b1b
app_bundle_id： com.ceshi.market
App secret： vXiA+EGBpUFUQ2yu8SC+Fg==

极光联盟广告推广目的与处理逻辑

开发者处理逻辑：

1. 当为DOWNLOAD_APK/DOWNLOAD_MARKET/WEIXIN_MINIPROGRAM时，开发者APP应先判断package_name对应的APP是否已安装，未安装时候才会进行广告展示，否则丢弃该条广告
2. 当为DEEPLINK时，开发者APP应先判断package_name对应的APP是否已安装，已安装时候才进行广告展示，否则丢弃该条广告
3. 当为QUICK_APP时，开发者APP应先判断package_name相对应的快应用APP是否已安装，已安装情况下才进行快应用拉取，否则丢弃该条广告
4. 当为DOWNLOAD_MARKET时，开发者APP应先判断package_name相对应的应用市场是否安装，已安装情况下才进行广告展示，否则丢弃广告

备用链接处理逻辑：

当推广目的为DEEPLINK时，为避免因Deeplink链接唤醒失败而影响用户体验，联盟特殊下发备用链接，开发者可根据以下判断逻辑使用打开备用链接。