通用说明

通用说明

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

示例代码-PHP

  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));
    }

示例代码-JAVA

  private String getSign(JSONObject requestJson){
    String time = String.valueOf(System.currentTimeMillis() / 1000);
    // 账号
    String userName = "xxxx@xx.cn";
    requestJson.put("user_name", userName);
    requestJson.put("time", time);
    // 授权码
    String secret = "5HnUP6r9Bs3zsGkfu5vxg6h4FtzpsjM2";
    SortedMap<String, String> params = new TreeMap<>();
    requestJson.keySet().forEach(key -> {
        params.put(key, requestJson.getString(key));
    });

    // 添加签名
    StringBuffer sb = new StringBuffer();
    params.forEach((k, v) -> {
        sb.append(k).append("=").append(v).append("&");
    });
    
    sb.append("secret=").append(secret);
    String sign = Md5Util.md5Encode(sb.toString(), "utf-8").toLowerCase();

    return sign;
  }

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	表示请求成功
  1	参数异常或数据错误
  20001	请填写正确 sign
  20002	sign 已过期，或time有误
  20004	非法sign，请检查sign生成算法
  21002	数据未产出

• 附录2. 行业

  industry_id	行业
  2	影视与直播
  6	搜索引擎
  8	综合
  10	阅读与工具书
  12	应用市场
  14	电商类
  16	工具类
  18	交友类
  20	教育类
  22	金融类
  26	生活类
  28	视频类
  30	小说类
  32	新闻类
  34	学习类
  36	音乐类
  38	运动类
  40	直播类
  42	阅读类
  44	游戏类
  55	医疗保健
  58	驾考类
  75	天气服务
  82	导购分享
  149	体育资讯

• 附录3. 广告位类型

  编码	名称
  2	Banner
  3	信息流
  4	开屏
  5	插屏
  6	激励视频
  8	全屏视频
  9	Draw信息流广告