广告位接口

广告位模块

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

创建应用广告位

Content-Type：application/json

POST

/openApi/sdkv2/appAdAdd

注意事项

广告位(ad_type)创建后不可修改
结算类型(fixed_type) 创建后不可修改
系统(os) 创建后不可修改

请求参数

参数名称	参数类型	参数描述	参数限制	是否必填
app_id	string	octopus 应用 id	根据创建应用接口返回的 app_id 指定需要在哪个应用下创建广告位	必填
third_adp_id	string	第三方广告位 id	第三方广告位 id	必填
os	int	系统	参数取值：1：iOS 2：Android 3：H5	必填
adp_name	string	广告位名字	字符长度不超过 50；同一个应用下广告位名字不能重复	必填
ad_type	int	广告位类型	取值范围`见通用说明附录3. 广告位类型`	必填
ad_size	string	广告尺寸	示列：640x960（宽x高）小写英文`x`	必填
fixed_type	int	结算类型	取值范围:1：固价 2：竞价	必填
ad_source	int	素材类型	1：图片 2：视频 3：图片加视频	必填
ad_template	int	信息流模板类型	0:大图模板,1:上文下图,2:上图下文,3:左图右文,4:左文右图	ad_type=3，必填
screen_direction	int	屏幕方向	1：竖屏 2：横屏	必填
ad_plug	int	插屏广告类型	1：全屏 2：半屏	ad_type=5，必填
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	int	ecpm 底价，单位：分		非必填，默认为0
bidding	int	实时竞价，实时返回真实报价	0：关闭 1：开启	非必填，默认关闭
white_list	string	白名单列表安卓端:oaid,ios端:idfa, 多个英文逗号分割		非必填
is_test	int	是否测试 1是0否		必填

返回内容

{
  "ret": 0,
  "desc": "ok",
  "data": {
    // octopus广告位id
    "adp_id": "afa98234f",
    "appAdId":"1234", // 兼容老版本octopus广告位id
    "third_adp_id":"1234_2", // 第三方广告位id
    // 广告位名称
    "adp_name": "wode",
    // 合作方应用id
    "app_id": 1674,
    // 广告类型 见 通用说明 附录3. 广告位类型
    "ad_type": 3,
    // 素材类型 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,
    "ecpm":0 //  ecpm 底价，单位：分
  }
}

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\": 3,\n \"ad_source\": 3,\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/sdkv2/updateAppAd

请求参数

参数名称	参数类型	参数描述	参数限制	是否必填
app_id	string	octopus 应用ID		必填
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	信息流模板类型	0:大图模板,1:上文下图,2:上图下文,3:左图右文,4:左文右图	非必填
ad_plug	int	插屏广告类型	1：全屏 2：半屏	非必填
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	int	ecpm 底价，单位：分		非必填，默认为0
bidding	int	实时竞价，实时返回真实报价	0：关闭 1：开启	非必填，默认关闭
white_list	string	白名单列表安卓端:oaid,ios端:idfa, 多个英文逗号分割	非必填
is_test	int	是否测试 1是0否	必填

返回内容

{
  "ret": 0,
  "desc": "ok",
  "data": {
    // 返回广告位所有数据
    // octopus广告位id
    "adp_id": "afa98234f",
    "appAdId":"1234", // 兼容老版本octopus广告位id
    "third_adp_id":"1234_2", // 第三方广告位id
    // 广告位名称
    "adp_name": "wode",
    // 合作方应用id
    "app_id": 1674,
    // 广告类型 见 通用说明 附录3. 广告位类型
    "ad_type": 3,
    // 素材类型 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,
    "ecpm":0 //  ecpm 底价，单位：分
  }
}

广告位列表

Content-Type：application/json

POST

/openApi/sdkv2/appAdList

请求参数

参数名称	参数类型	参数描述	参数限制	是否必填
app_id	string	octopus 应用 id	app_id 作为唯一值	非必填
adp_id	string	octopus 应用下广告位 id	adp_id 作为唯一值	非必填
appAdId	string	兼容octopus 应用下广告位 id	appAdId 作为唯一值	非必填
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",
            "appAdId":"1234", // 兼容老版本octopus广告位id
            "third_adp_id":"1234_2", // 第三方广告位id
            // 广告位名称
            "name": "wode",
            // octopus应用id
            "app_id": 1674,
            // 广告类型 见 通用说明 附录3. 广告位类型
            "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,
            "ecpm":0 //  ecpm 底价，单位：分
        }
    }
}

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

合作方以 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
}

Octopus

广告位模块​

创建应用广告位​

POST​

注意事项​

请求参数​

返回内容​

java 示例​

修改应用广告位​

POST​

请求参数​

返回内容​

广告位列表​

POST​

请求参数​

返回内容​

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

广告位模块

创建应用广告位

POST

注意事项

请求参数

返回内容

java 示例

修改应用广告位

POST

请求参数

返回内容

广告位列表

POST

请求参数

返回内容

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