Starter Kit
Start Here

SSP平台集成文档

本集成文档旨在为开发者提供详细的指导，以便通过标准OpenRTB协议和VAST TAG URL方式与我们的SSP（Supply Side Platform）进行对接。我们将介绍必要的接口规格及对开发者的基本要求。

1. 开发者准备事项

  • 账号注册：首先需要在我们平台上注册一个账号，并完成企业认证。

  • API密钥获取：登录后，在“我的账户”页面查看/复制API密钥。该密钥将用于所有API调用的身份验证。

  • 了解基本概念：熟悉OpenRTB (Real-Time Bidding)、Native1.1、VAST以及数字广告领域相关术语IAB Tech Lab Standards and Software。

  • 创建应用

    • 进入【媒体管理】→【应用管理】模块。

    • 填写应用基本信息。

    • 上传应用Logo并保存。

  • 创建广告位

    • 进入【广告位管理】模块，点击【新建】选择目标应用。

    • 配置广告位参数：

      • 广告位ID（系统自动生成）

      • 广告类型

      • 支持的广告尺寸

    • 完成配置后提交审核，审核通过后即可启用。

  • 集成测试

    • 使用测试广告位ID与API密钥，模拟请求，开始测试。

简化流程

::: 直接向支持团队申请API密钥 -> 申请广告位 -> 集成测试 :::

2. OpenRTB 集成指南

2.1 请求格式

  • 使用HTTP POST方法发送请求。

  • Content-Type: application/json;charset=UTF-8

  • Accept-Encoding: gzip

  • Endpoint: https://ssp-bid.superctv.com/bid

  • 请求体应遵循OpenRTB 2.5规范构建JSON对象。

示例请求 - video

curl --location --request POST 'https://ssp-bid.superctv.com/bid' \
--header 'Content-Type: application/json' \
--header 'Accept-Encoding: gzip' \
--header "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
--data '{
  "allimps": 0,
  "app": {
    "bundle": "5xdssd Vedio",
    "content": {
      "contentrating": "",
      "genre": "Documentary",
      "id": "60ad4dc55ea1237492f39d1a",
      "language": "EN",
      "season": "",
      "series": "",
      "title": "E3. A Refuge For Orangutans"
    },
    "domain": "us-api.wesdreamer.homes",
    "ext": {},
    "name": "TCL%20TV%20",
    "publisher": {
      "id": "87b8f7031f644fac8daf9ebdbe8fe4e4"
    },
    "storeurl": "https://channelstore.roku.com/details/591991"
  },
  "at": 1,
  "badv": [],
  "bapp": [],
  "cur": [
    "USD"
  ],
  "device": {
    "connectiontype": 0,
    "devicetype": 3,
    "ext": {
      "ifa_type": "rida"
    },
    "geo": {
      "city": "Mableton",
      "country": "USA",
      "ipservice": 3,
      "lat": 33.8187,
      "lon": -84.5824,
      "region": "US",
      "type": 2
    },
    "ifa": "92764176-1c77-613d-9fa5-0fd2f7f3da0a",
    "ip": "24.125.30.52",
    "make": "Roku",
    "model": "DVP",
    "os": "Roku OS",
    "osv": "15.0",
    "ua": "Roku/DVP-15.0 (15.0.4.5537-88)"
  },
  "id": "0420142812573399",
  "imp": [
    {
      "bidfloor": 10,
      "bidfloorcur": "USD",
      "displaymanager": "Super CTV_oRTB",
      "displaymanagerver": "1.0",
      "id": "1",
      "instl": 0,
      "secure": 0,
      "tagid": "1000465120",
      "video": {
        "boxingallowed": 1,
        "h": 1080,
        "linearity": 1,
        "maxduration": 65,
        "maxextended": 0,
        "mimes": [
          "video/mp4"
        ],
        "minduration": 5,
        "pos": 0,
        "protocols": [
          3,
          6
        ],
        "skip": 0,
        "skipafter": 0,
        "skipmin": 0,
        "w": 1920
      }
    }
  ],
  "source": {
    "ext": {
      "schain": {
        "ver": "1.0",
        "complete": 1,
        "nodes": [
        ]
      }
    }
  },
  "test": 0,
  "tmax": 2500,
  "user": {
    "ext": {
      "gdpr": 0
    },
    "id": ""
  },
  "wlang": [
    "en"
  ]
}'

示例请求 - banner


curl --location --request POST 'https://ssp-bid.superctv.com/bid' \
--header 'Content-Type: application/json' \
--header 'Accept-Encoding: gzip' \
--header "Authorization: Bearer ${YOUR_ACCESS_TOKEN}" \
--data '{
    "allimps": 0,
    "app": {
        "bundle": "462678375",
        "cat": [
            "IAB3"
        ],
        "ext": {
            "inventorypartnerdomain": "hornet.com"
        },
        "id": "2498735",
        "keywords": "гей соціальна,lgbtq dating,guys,jackd,relacionamento,dating app gay,encontros app,daddy,gay dating app,fetiche,site gay,gay chat,bear,gayr,hornet гей соціальна,boys,gay romeo,bears,rencontre lgbt,gaymec,app relacionamento,grindr,a4a,trans,surge,encontros,action gay,sugar daddy,bisexual,gays,lgbtq,rencontres gay,taimi,gayhookup,hornet гей,blued,gay apps,scruff,app encontros,гей знакомства,gay hookup,gay app,chat uol,app gay,gay,lgbt,free dating apps,хорнет,хорнет скачать бесплатно,gay dating,би,гей,bi,recon,chat date,site de rencontre gay,rencontre gay,sniffies,jock,chat gay,гей соціальна мережа,grinder,bate papo uol,romeo,gays dating app free,,",
        "name": "Hornet - Gay Dating & Chat",
        "publisher": {
            "id": "1007194",
            "name": "Queer Networks Inc."
        },
        "storeurl": "https://itunes.apple.com/TH/app/id462678375?mt=8&uo=4"
    },
    "at": 1,
    "bcat": [
        "IAB24",
        "IAB26",
        "IAB9-9",
        "IAB14-1",
        "IAB23-4",
        "IAB23-7",
        "IAB25-1"
    ],
    "cur": [
        "USD"
    ],
    "device": {
        "carrier": "True Mobile",
        "connectiontype": 3,
        "devicetype": 4,
        "ext": {
            "batterysaver": 0,
            "airplane": 0,
            "charging": 0,
            "darkmode": 0,
            "ifv": "82E9AA76-3BF1-49B1-A972-5C363D1F6283",
            "batterylevel": 7
        },
        "geo": {
            "accuracy": 56,
            "city": "Bangkok",
            "country": "THA",
            "ext": {
                "org": "True Mobile",
                "isp": "True Mobile"
            },
            "lat": 13.59,
            "lon": 100.61,
            "region": "10",
            "type": 1,
            "utcoffset": 420,
            "zip": "10310"
        },
        "geofetch": 1,
        "h": 667,
        "ifa": "33BCDE13-DF54-460F-84F5-3A1D384CFC6A",
        "ip": "27.55.90.61",
        "js": 1,
        "language": "th",
        "make": "Apple",
        "model": "iPhone",
        "os": "iOS",
        "osv": "18.1.1",
        "pxratio": 2.0,
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
        "w": 375
    },
    "ext": {
        "schain": {
            "ver": "1.0",
            "nodes": [
                {
                    "asi": "pubnative.net",
                    "hp": 1,
                    "rid": "6cc27620000000009cd7800d9f4db78b",
                    "sid": "1009105"
                },
                {
                    "asi": "verve.com",
                    "hp": 1,
                    "rid": "6cc27620000000009cd7800d9f4db78b",
                    "sid": "1009105"
                }
            ],
            "complete": 1
        }
    },
    "id": "fa666020000000009a24b4fcba1ddd6c",
    "imp": [
        {
            "banner": {
                "api": [
                    3,
                    5,
                    6,
                    7
                ],
                "format": [
                    {
                        "h": 50,
                        "w": 320
                    },
                    {
                        "h": 50,
                        "w": 300
                    }
                ],
                "h": 50,
                "pos": 0,
                "w": 320
            },
            "bidfloor": 0.0012434154,
            "bidfloorcur": "USD",
            "displaymanager": "HyBid",
            "displaymanagerver": "3.1.4",
            "ext": {
                "hb": 1
            },
            "id": "1",
            "instl": 0,
            "secure": 1,
            "tagid": "1666666666"
        }
    ],
    "regs": {
        "ext": {
            "consent": "",
            "gdpr": 0
        }
    },
    "source": {
        "ext": {
            "omidpv": "1.5.2",
            "omidpn": "Pubnativenet",
            "schain": {
                "ver": "1.0",
                "nodes": [
                    {
                        "asi": "pubnative.net",
                        "hp": 1,
                        "rid": "6cc27620000000009cd7800d9f4db78b",
                        "sid": "1009105"
                    },
                    {
                        "asi": "verve.com",
                        "hp": 1,
                        "rid": "6cc27620000000009cd7800d9f4db78b",
                        "sid": "1009105"
                    },
                    {
                        "asi": "smaato.com",
                        "hp": 1,
                        "rid": "4158bb5f000000009ea87bd6dfc4d132",
                        "sid": "1100049757"
                    },
                    {
                        "asi": "pubnative.net",
                        "hp": 1,
                        "rid": "fa666020000000009a24b4fcba1ddd6c",
                        "sid": "1007194"
                    }
                ],
                "complete": 1
            }
        },
        "fd": 1,
        "pchain": "d641df8625486a7b:1009105-0c8f5958fc2d6270:1009105-07bcf65f187117b4:1100049757-d641df8625486a7b:1007194"
    },
    "test": 0,
    "tmax": 2500,
    "user": {
        "ext": {
            "sessionduration": 12934,
            "impdepth": 1,
            "consent": ""
        },
        "gender": "M",
        "id": "05ebe0a8-61fd-5b32-b3f5-261f86ba3572",
        "yob": 2000
    }
}'

2.2 响应格式

  • 响应状态码说明

我们的SSP平台使用以下HTTP状态码返回请求结果：

状态码描述处理建议
200 OK成功响应，包含竞价结果。解析响应中的seatbid字段获取广告信息，并展示广告内容。
204 No Content无填充响应，表示当前无可用广告。应用需处理无广告返回的情况，例如展示默认内容或继续请求其他广告源。
400 Bad Request请求无效，通常由参数错误、API密钥问题或请求格式错误引起。检查请求参数（如API密钥、广告位ID）、JSON格式及必填字段，修正后重新提交请求。
  • 示例响应

200 OK（成功）

{
  "id": "12345",
  "seatbid": [
    {
      "bid": [
        {
          "id": "bid123",
          "impid": "imp1",
          "price": 0.01,
          "adm": "<VAST XML广告内容>",
          "adomain": ["example.com"],
          "nurl": "http://example.com/winnotice?imp=imp1&price=${AUCTION_PRICE}"
        }
      ]
    }
  ]
}

204 No Content（无填充）

{
  "requestId": "12345"
}

400 Bad Request（请求错误）

{
  "requestId": "12345",// 如果请求没有则没有
  "reason": "" // x-adx-enable-trace为true时返回具体原因
}
  • 错误代码与原因

x-adx-enable-trace为true时reason字段会返回具体错误类型，常见reason包括：

code说明
placement not found缺少placement
empty auth缺少token
ua invalidua非法
device invalid设备非法
publisher not found开发者信息不正确
invalid request pathurl path不正确
api request id emptyrequest id为空
......

3. VAST TAG URL 集成指南

3.1 获取VAST Tag

  • 使用HTTP GET方法发送请求。

  • Endpoint: https://ssp-bid.superctv.com/vast

  • 一些必要参数

    字段类型是否必须参数说明
    tokenstringrequired固定，平台分配
    publisherstringrequired固定，平台分配
    tagidstringrequired固定，平台分配

  • 其它参数参考

Macros - Spring Serve Documentation - Confluence

示例请求

GET https://ssp-bid.superctv.com/vast?token=平台分配的token&tagid=平台分配的广告位id&publisher=平台分配的id&..............

3.2 响应格式

  • 响应格式完全遵循 VAST格式规范，确保您的播放器支持VAST 3.0及以上版本

4. 安全性考量

  • 所有通信必须使用HTTPS协议。

  • 请妥善保管您的API密钥，不要将其硬编码在客户端应用中。

  • 对敏感数据进行加密存储。

5. 技术支持

遇到任何问题时，请联系技术支持团队

以上就是关于如何通过OpenRTB和VAST TAG URL方式与我们的SSP平台进行集成的全部信息。希望这份文档能够帮助您顺利完成集成工作！

Was this page helpful?
Built with Documentation.AI

Last updated today