广告位模块

广告位模块

广告位管理相关功能，广告位的创建、修改

创建应用广告位

Content-Type：application/json

POST

/openApi/thirdChannel/adpAdd

请求参数

| 参数名称 | 参数类型 | 参数描述 | 参数限制 | 是否必填 | | -------------- | -------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------- | | app_id | string | octopus 应用 id | 根据创建应用接口返回的 app_id 指定需要在哪个应用下创建广告位 | 必填 | | third_adp_id | string | 第三方广告位 id | 第三方广告位 id | 必填 | | adp_name | string | 广告位名字 | 字符长度不超过 50；同一个应用下广告位名字不能重复 | 必填 | | ad_type | int | 广告类型 | 取值范围:1：开屏 4：信息流广告 7：全屏视频广告 9：激励视频广告 10：Draw 视频广告 15：插屏广告 | 必填 | | ad_source | int | 素材类型 | 1：图片 2：视频 3：图片加视频 | 必填 | | ad_template | int | 信息流模板类型 | 1：上文下图 2：左图右文 3：左文右图 4：文字悬浮 | ad_type=4，必填 | | ad_plug | int | 插屏广告类型 | 1：全屏 2：半屏 | ad_type=15，必填 | | reward_setting | int | 激励视频广告位是否开启回调 | 是否开启服务器回调 0：关闭 1：开启 | 激励视频广告位，非必填，默认不开启 | | reward_name | string | 奖励名称(开启服务器回调时填写 reward_setting=1) | 长度限制为：最多包含 20 个字符 | reward_setting=1 时必填 | | reward_sum | int | 奖励数量(开启服务器回调时填写 reward_setting=1) | >=1 | reward_setting=1 时必填 | | reward_url | string | 回调地址(开启服务器回调时填写 reward_setting=1) | 回调 URL 需要以 http：//或 https：//开头 | | reward_setting=1 时必填 | | reward_secret | string | 激励广告服务端校验密钥 | 32 位随机大小写字母和数字组成 | reward_setting=1 时必填 | | ecpm_setting | int | 自设底价开关 | 0：关闭 1：开启 | 非必填，默认关闭 | | ecpm | int | ecpm 底价，单位：元 | | ecpm_setting=1 时，必填 | | bidding | int | 实时竞价，实时返回真实报价 | 0：关闭 1：开启 | 非必填，默认关闭 | | filter_rule | string | 广告过滤规则 英文,分割 | 取值范围:医院,赌博,等 | 非必填 |

返回内容

{
  "ret": 0,
  "desc": "ok",
  "data": {
    // octopus广告位id
    "adp_id": "afa98234f",
    // 广告位名称
    "adp_name": "wode",
    // 合作方应用id
    "appid": 1674,
    // 广告类型 1：开屏  4：信息流广告  7：全屏视频广告  9：激励视频广告  10：Draw视频广告 15：插屏广告
    "ad_type": 1,
    // 素材类型 1：图片 2：视频 3：图片加视频
    "ad_source": 3,
    // 是否需要服务器回调
    "reward_setting": 1,
    // 奖励名称
    "reward_name": "coin",
    // 奖励数量
    "reward_sum": 2,
    // 回调地址
    "reward_url": "https://fc-mp-321186b3-2c50-480b-9c19-98a865088d84.next.bspapp.com/1233499384/1/2/276670",
    // reward_secret 如广告位开启激励视频回调，则该值必须返回
    "reward_secret": "2d3764deb6ed691768091bd98e04df57",
    // 应用内竞价
    "bidding": 1
  }
}

java 示例

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"app_id\": \"1000\",\n \"third_adp_id\": \"1975968129_2\",\n \"adp_name\": \"测试\",\n \"ad_type\": 1,\n \"ad_source\": 3,\n \"ecpm_setting\": 0,\n \"bidding\": 1,\n \"user_name\": \"lofterad@163.com1\",\n \"time\": 1745830572,\n \"sign\": \"4e3db8d199a93efbd15b2774b2be2089\"\n}");
Request request = new Request.Builder()
   .url("http://xxx.xxx.xxx/openApi/thirdChannel/adpAdd")
   .method("POST", body)
   .addHeader("User-Agent", "Apifox/1.0.0 (https://apifox.com)")
   .addHeader("Content-Type", "application/json")
   .addHeader("Accept", "*/*")
   .addHeader("Host", "localhost:8080")
   .addHeader("Connection", "keep-alive")
   .build();
Response response = client.newCall(request).execute();

修改应用广告位

Content-Type：application/json

POST

/openApi/thirdChannel/adpUpdate

请求参数

| 参数名称 | 参数类型 | 参数描述 | 参数限制 | 是否必填 | | -------------- | -------- | ----------------------------------------------- | ------------------------------------------------- | -------------------------------- | ----------------------- | | adp_id | string | octopus 广告位 id | 根据创建广告位接口返回的 adp_id 唯一值 | 必填 | | third_adp_id | string | 第三方广告位 id | 第三方 adp_id | 必填 | | adp_name | string | 广告位名字 | 字符长度不超过 50；同一个应用下广告位名字不能重复 | 必填 | | ad_source | int | 素材类型 | 1：图片 2：视频 3：图片加视频 | 必填 | | ad_template | int | 信息流模板类型 | 1：上文下图 2：左图右文 3：左文右图 4：文字悬浮 | ad_type=4，必填 | | ad_plug | int | 插屏广告类型 | 1：全屏 2：半屏 | ad_type=15，必填 | | reward_setting | int | 激励视频广告位是否开启回调 | 是否开启服务器回调 0：关闭 1：开启 | 激励视频广告位，非必填，默认关闭 | | reward_name | string | 奖励名称(开启服务器回调时填写 reward_setting=1) | 长度限制为：最多包含 20 个字符 | reward_setting=1 时必填 | | reward_sum | int | 奖励数量(开启服务器回调时填写 reward_setting=1) | >=1 | reward_setting=1 时必填 | | reward_url | string | 回调地址(开启服务器回调时填写 reward_setting=1) | 回调 URL 需要以 http：//或 https：//开头 | | reward_setting=1 时必填 | | reward_secret | string | 激励广告服务端校验密钥 | 32 位随机大小写字母和数字组成 | reward_setting=1 时必填 | | ecpm_setting | int | 自设底价开关 | 0：关闭 1：开启 | 非必填，默认关闭 | | ecpm | int | ecpm 底价，单位：元 | | ecpm_setting=1 时，必填 | | bidding | int | 实时竞价，实时返回真实报价 | 0：关闭 1：开启 | 非必填，默认关闭 | | filter_rule | string | 广告过滤规则 英文,分割 | 取值范围:医院,赌博,等 | 非必填 |

返回内容

{
  "ret": 0,
  "desc": "ok",
  "data": {
    // 返回广告位所有数据
    // octopus广告位id
    "adp_id": "afa98234f",
    // 广告位名称
    "adp_name": "wode",
    // 合作方应用id
    "appid": 1674,
    // 广告类型 1：开屏  4：信息流广告  7：全屏视频广告  9：激励视频广告  10：Draw视频广告 15：插屏广告
    "ad_type": 1,
    // 素材类型 1：图片 2：视频 3：图片加视频
    "ad_source": 3,
    // 是否需要服务器回调
    "reward_setting": 1,
    // 奖励名称
    "reward_name": "coin",
    // 奖励数量
    "reward_sum": 2,
    // 回调地址
    "reward_url": "https://fc-mp-321186b3-2c50-480b-9c19-98a865088d84/callback/v2/v3/1233499384/1/2/276670",
    // reward_secret 如广告位开启激励视频回调，则该值必须返回
    "reward_secret": "2d3764deb6ed691768091bd98e04df57",
    // 应用内竞价
    "bidding": 1
  }
}

应用列表

Content-Type：application/json

POST

/openApi/thirdChannel/adpList

请求参数

|参数名称|参数类型|参数描述|参数限制|是否必填| |app_id|string|octopus 应用 id|app_id 作为唯一值|非必填| |adp_id|string|octopus 应用下广告位 id|adp_id 作为唯一值|非必填| |page|int|第几页|默认：1|非必填| |page_size|int|每页多少条|默认：100|非必填|

返回内容

{
    "ret": 0,
    "desc": "ok",
    "data": {
        "page":1,        // 第几页
        "page_size":100,    // 每页多少条
        "total":4593,    // 总共多少条
        "list":[    // 数据 返回广告位详情所有数据 这里只是示例 并未返回所有参数
        {
            // octopus广告位id
            "adp_id": "afa98234f",
            // 广告位名称
            "name": "wode",
            // octopus应用id
            "app_id": 1674,
            // 广告类型 1：开屏  4：信息流广告  7：全屏视频广告  9：激励视频广告  10：Draw视频广告 15：插屏广告
            "ad_type": 1,
            // 素材类型 1：图片 2：视频 3：图片加视频
            "ad_source": 3,
            // 是否需要服务器回调
            "reward_setting": 1,
            // 奖励名称
            "reward_name": "coin",
            // 奖励数量
            "reward_sum": 2,
            // 回调地址
            "reward_url": "https://fc-mp-321186b3-2c50-480b-9c19-98a865088d84/callback/v2/v3/1233499384/1/2/276670",
            // reward_secret 如广告位开启激励视频回调，则该值必须返回
            "reward_secret": "2d3764deb6ed691768091bd98e04df57",
            // 应用内竞价
            "bidding":1,

        }
    }
}

激励视频广告位服务器回调说明

合作方以 GET 方式请求广告位的 reward_url 回调地址，并拼接以下参数进行回传： slotId=%s&appId=%s&transId=%s&userId=%s&extrai=%s&sign=%s&name=%s&count=%s

字段定义	字段名称	字段类型	备注
slotId	签名后的广告位 ID	string	签名后的广告位 ID，需要可校验
appId	APP ID	string	应用 ID，需要可校验
transId	交易 id	string	完成观看的唯一交易 ID
sign	签名后的 transId	string	必须验证的签名信息
userId	用户 id	string	调用 SDK 传入并透传，应用对用户的唯一标识，如无需要则为空
extra	其他信息	string	调用 SDK 传入并透传，如无需要则为空
name	奖品名称	string	需要就联系运营配置，如无需要则为空
count	奖品数量	string	需要就联系运营配置，如无需要则为空

具体示例：

http://开发者回调地址/sdk/callback?slotId=%s&appId=%s&transId=%s&userId=%s&extra=%s&sign=%s&name=%s&count=%s

服务端验证说明

当选择需要服务端验证时，开发者需要按照以上接口进行开发，并向运营提供回调 URL 让运营帮忙配置一下回调 URL。服务端回调是指在用户看完视频达到奖励条件时，章鱼广告 SDK 服务端会向开发者服务端发送一个验证请求，同时客户端会给出 onReward 回调，开发者根据回调进行奖励发放，因为奖励回调和服务端验证请求是同时发送的，开发者后台收到验证请求可能会有延迟或网络原因上的失败，开发者需要平衡用户体验与奖励验证。

补充： 章鱼广告 SDK 后台向上述 URL 发起请求后，您会在服务端收到某个 transId 的请求，如果签名验证正确，那么此 transId 对应的曝光为有效曝光

签名生成方式：

sign = sha256(transid:secret)

其中 transId 为交易 id，secret 运营配置服务端 URL 时获取到的密钥，配置好后跟运营要。

约定返回参数

字段名称	字段定义	字段类型	备注
isValid	校验结果	bool	判定结果，是否发放奖励

注意：按照 SDK 要求需要服务器判断的回调 url 是一个 get 请求默认返回的是一个 json 字符串{"isValid": true}

示例：

{
    "isValid": true
}