通用说明

通用说明

SDK媒体自助接入API文档的统一说明

接口说明

本 API文档所涉及接口均遵循 HTTP 协议，所有请求的ContentType 在不明确指定的情况下均为 multipart/form-data，所有返回的 ContentType 在不明确指定的情况下均为 application/json。 您可以使用任何支持 HTTP 协议和 JSON 格式的编程语言开发应用程序。 有关标准 HTTP 协议，可参考 RFC2616 或 维基百科-HTTP 相关介绍。 有关 JSON 数据格式，可参考 JSON.ORG 或 维基百科–JSON 相关介绍。

• 正式环境域名: https://ad.adintl.cn

术语说明

• 广告场景定义：
  • 开屏：APP开启后全屏沉浸式展示广告
  • 信息流：模板信息流广告
  • 激励视频：完整观看视频广告以免费获得游戏奖励的广告
  • 全屏视频：以全屏形式播放的视频广告
  • Draw视频广告：竖屏视频信息流广告样式
  • 插屏广告（半屏广告）
• 接口提供方：Octopus
• 接口调用方：第三方广告渠道商

对接流程

• 第1步，第三方广告渠道商根据本文档完成相关接口开发工作。
• 第2步，开发对接：第三方广告渠道商向接口提供方Octopus运营接口人申请环境密钥，并进行测试联调。
• 第3步，正式环境上线：测试联调通过后，上线。

接口详述

通用声明

1. 权限认证 第三方广告渠道商 在调用 API 会通过参数签名 sign 进行权限认证，第三方广告渠道商应当在签名验证通过的情况下再做相应处理，防止接口被非法调用。

2. 编码方式 若无特殊说明或响应头中的Content-Type未指定编码，请求和响应中的字符编码均使用 UTF-8（无 BOM 头）。

3. URL定义 URL请求域名由Octopus提供，协议：必须使用HTTPS。本文接口详述中使用的请求URL均为示例，实际上线时的 URL 以合作方提供的为准。

4. 通用参数 以下是每个接口都会用到的通用参数，详细定义为：

   名称	类型	必填	描述
   user_name	string	是	合作方账号，由第三方广告渠道商向Octopus运营接口人获取，此参数放置到请求body中
   time	int	是	发起请求时的unix时间戳（精确到秒），此值跟接收到请求时的服务器时间戳值偏差（正负）, 超过120秒（2分钟）时，合作方可以忽略该请求；（请使用 Asia/Shanghai时区），此参数放置到请求body中
   sign	string	是	签名字符串，生成算法见下方说明，此参数放置到请求body中

4.1 sign 生成算法 设所有发送或者接收到的数据为集合M，将集合M内参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即 key1=value1&key2=value2…）拼接成字符串 stringA。

• 注意： 参数名称区分大小写； 参数取值不需要 urlencode 参数如果为空不参与签名，数字0需要参与签名 上传图片 file 参数不参与签名 在 stringA 最后拼接上 secret 得到 stringSignTemp 字符串，并对 stringSignTemp 进行 MD5 运算，再将得到的字符串所有字符转换为小写，得到 sign 值 signValue。 签名中使用的 user_name(账号)、secret(授权码) 参数由 Octopus 运营方提供。

4.2 sign 生成示例 下面举例说明如何生成 sign（php语言为例）。 假设生成 token的各个参数取如下数值： user_name：xxxx@xx.cn secret：5HnUP6r9Bs3zsGkfu5vxg6h4FtzpsjM2

示例代码：

  function getSign()
    {
        $params = [
            'user_name' => 'xxxx@xx.cn',
            'app_name' => '应用名称',
            'time' => time()
        ];
        $secret = '5HnUP6r9Bs3zsGkfu5vxg6h4FtzpsjM2';
        ksort($params);
        $signStr = urldecode(http_build_query($params));
        $signStr .= '&secret=' . $secret;
        return strtolower(md5($signStr));
    }

5. API请求

• HTTP Method 如无特殊说明，add、update API请求的HTTP Method为POST get API请求的HTTP Method均为GET

• HTTP Header 调用方应遵循HTTP协议设置相应的Header。

6. API响应

• HTTP状态码 支持HTTP标准状态码，具体如下：

  状态码	名称	描述
  200	成功	当 API 请求被正确处理，且能按设计获取结果时，返回该状态码；亦适用于批量接口返回部分结果
  3xx	跳转	在特定情况下，API 可能会返回这些状态码，需要由接口调用方按照 HTTP 标准来处理
  4xx	接口调用方端错误	由接口调用方端原因造成的错误
  5xx	接口合作方服务器端错误	接口合作方 API 或其下层服务发生内部错误

• HTTP Header 接口合作方API响应的 Content-Type 应为 application/json。

• HTTP Body 响应的JSON数据中包含三部分内容，分别为状态码、返回信息和数据，如下表所示：

  名称	类型	必填	描述
  ret	int	是	状态码：0表示成功 具体见状态码列表
  desc	string	是	返回信息：若有错误，此字段为详细的错误信息
  data	json	array 或 json object	否

7. 接口开发注意事项 因网络等原因有可能数据未正常接收，这时需要重复请求接口，故如果该数据已经处理过，则按照对应接口应答示例正常返回即可，不用做特殊处理

附录

• 附录1. 状态码定义

  状态码	返回描述
  0	表示请求成功
  20001	请填写正确 sign
  20002	sign 已过期，或time有误
  20004	非法sign，请检查sign生成算法
  21002	数据未产出

• 附录2. 行业

  行业	industry_id	行业	industry_id	行业	industry_id
  日程备忘	2000701	语言学习	2000903	消除游戏	1001602
  办公室软件	2000704	教育工具	2000902	模拟经营	1000505
  文件管理	2000702	汽车资讯	2001002	益智休闲	1001501
  网络云盘	2000703	驾照考试	2001001	游戏助手	1001901
  输入法	2000106	汽车交易	2001004	游戏平台	1001401
  浏览器	2000102	违章查询	2001003	其他手游	1001901
  电池插件	2000105	理财服务	2001101	报刊杂志	2001302
  安全防护	2000101	股票证券	2001103	有声听书	2001304
  内存清理	2000104	彩票双色球	2001104	小说阅读	2001305
  WIFI	2000103	支付	2001102	手机漫画	2001301
  账号辅助	2000109	旅游服务	2001207	幽默段子	2001303
  应用商店	2000102	用车服务	2001205	育儿工具	2001903
  主题美化	2000108	地图导航	2001203	孕育社区	2001901
  电话通讯	2000111	公交服务	2001206	经期健康	2001902
  性能优化	2000110	共享单车	2001202	垂类资讯	2001602
  万年历	2000401	航班服务	2001204	综合资讯	2001603
  天气服务	2000404	火车服务	2001201	网赚资讯	2001601
  运势信仰	2000403	网络K歌	2001401	相机	2000502
  闹钟	2000406	音乐播放器	2001405	图片美化	2000501
  红包助手	2000405	在线音乐	2001404	设计制作	2000503
  计算器	2000408	广播电台	2001402	体育资讯	2001801
  日记手账	2000402	音乐乐器	2001403	体育直播	2001802
  辅助工具	2000407	在线视频	2001505	平台	2000601
  导购分享	2000803	在线直播	2001502	美食菜谱	2000307
  二手交易	2000804	视频播放器	2001501	求职招聘	2000305
  移动电商	2000802	短视频	2001504	快递物流	2000306
  优惠比价	2000801	电视视频	2001506	在线团购	2000302
  运动健身	2000203	视频工具	2001503	房屋租赁	2000301
  医疗问询	2000201	婚恋交友	2001705	装修服务	2000304
  健康养生	2000202	社交交友	2001706	票务服务	2000303
  学前教育	2000907	生活社区	2001703	网赚平台	2000310
  词典翻译	2000905	微博社交	2001704	运营商服务	2000309
  K12	2000906	问答社区	2001701	美妆美发	2000308
  高等教育	2000904	论坛贴吧	2001702
  职业培训	2000901	棋牌游戏	1000803

• 附录3. H5广告位

  广告位样式	adp_style
  原生缩略图	1
  原生图文	2
  原生三图	3
  原生大图	4
  原生多图	5
  原生橱窗	6

  广告位比例	adp_proportion
  20：06	1
  20：12	2
  20：15	3
  700：250 2图	4
  700：250 3图	5
  300：60	6
  300：250	7
  250：250	8
  200：200	9
  336：280	10
  125：125	11
  180：150	12
  800：250	13
  800：160	14

  广告位高度	adp_height
  100px	1
  500px	2
  130px	3
  282px	4

  广告位位置	adp_site
  图片靠左	1
  图片靠右	2