API 广告集成

如果您希望能在自己的应用中无感集成广告，不会出现明显的 Popup 或者 Banner ，您可以通过 API 的方式来实现。

注意

此方式对接成本较高，请谨慎使用，尽量使用 SDK 广告集成 的方式接入

此功能目前处于测试阶段，只对部分用户开放，在未来版本中可能移除

提示

请在前端实现广告的获取和上报，这样系统才可以获取到访问用户的 IP 地址，从而做广告区域匹配

前置要求

• 知道在什么地方展示广告，如果没有，请先查看 广告集成示例
• 已经获取了 BlockId，如果没有，请先查看 获取 BlockId

1. 获取广告 API

接口描述

此 API 用于获取广告信息，您需要将返回的广告信息嵌入到您的产品中。

提示

在生产环境中，用户点击过广告后，10分钟后不会再次展示该广告

测试环境无此限制

提示

建议一次性获取多个广告，然后同时展示出来，提高广告的点击率

请求方法

GET https://app.ton.ai/api/v2/openapi/matching/ad

请求参数

参数名	位置	类型	必填	描述
adBlockId	query	string	是	广告位 ID，从平台 -> 广告位 -> ID 获取
openId	query	string	是	用户的唯一标识
type	query	string	是	openId 对应的类型，目前仅支持 'telegram'
limit	query	number	是	一次性返回广告数量限制，必须大于 0 且小于 10
x-api-key	header	string	是	API 密钥，如何获取 App Key?
debug	header	boolean	否	debug=true 时，返回测试广告，默认值为 false

提示

在生产环境中，要设置 debug=false

返回值解析

参数名	类型	描述
adBlockId	string	广告位 ID
adId	string	广告 ID
campaignId	string	广告活动 ID
icon	string	广告图标 URL
image	string	广告图片 URL
text	string	广告文本
destination	object	广告目标信息
destination.actionType	string	广告动作类型，例如 'visit.website'
destination.url	string	广告目标 URL

完整请求示例

发起请求：

curl --request GET \
     --url 'https://staging.ton.ai/api/v2/openapi/matching/ad?adBlockId=66f65d8b2ec147ec042aa530&openId=16213622061&type=telegram&limit=2' \
     --header 'accept: application/json' \
     --header 'x-api-key: moJHPwHiGpSP7Lrz88xY1IAXXamF90'

成功响应会返回广告列表数据，状态码为 200。

{
  "data": {
    "msg": "ads success",
    "success": true,
    "ads": [
      {
        "icon": "https://file.pea.ai/ad_avatar_development/664f211f8135c60011c30dab_222777_PEPE-1.png",
        "adBlockId": "66f65d8b2ec147ec042aa530",
        "adId": "66f65baa2ec147ec042aa4a1",
        "campaignId": "66f65baa2ec147ec042aa49f",
        "image": "https://file.pea.ai/ad_development/664f211f8135c60011c30dab_801668_GoPlus.jpg",
        "text": "test ton ai",
        "destination": {
          "actionType": "visit.website",
          "url": "https://app.ton.ai"
        }
      }
    ]
  },
  "code": 0,
  "message": "success"
}

2. 上报 Click 事件 API

接口描述

此 API 用于在用户点击广告时上报 Click 事件。流量主需要在用户点击广告时调用此接口。

注意

请勿上报虚假的 Click 事件

广告主和流量主双方的数据都会上报到 Ads3 平台，如果您上报了虚假的 Click 事件，会导致双边的数据不一致，系统检测到此类行为将会有相应的惩罚措施。

请求方法

POST https://app.ton.ai/api/v2/openapi/ad/event/report

请求参数

请求参数应为 JSON 格式，包含以下字段：

字段名	类型	必填	描述
eventType	string	是	事件类型，固定值为 "click"
eventData	object	是	事件数据，包含以下字段

eventData 对象包含以下字段：

字段名	类型	必填	描述
adBlockId	string	是	广告位 ID，从平台 -> 广告位 -> ID 获取
telegramUserId	string	是	用户的唯一 Telegram ID
adId	string	是	上一个 API 返回了 adId, 用户点击的广告 ID
campaignId	string	是	用户点击的广告所属的广告活动 ID

完整请求示例

发起请求：

curl --request POST \
     --url https://staging.ton.ai/api/v2/openapi/ad/event/report \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: moJHPwHiGpSP7Lrz88xY1IAXXamF90' \
     --data '
{
  "eventType": "click",
  "eventData": {
    "adBlockId": "66f65d8b2ec147ec042aa530",
    "telegramUserId": "16213622061",
    "adId": "66f65baa2ec147ec042aa4a1",
    "campaignId": "66f65baa2ec147ec042aa49f"
  }
}
'

成功响应会返回广告列表数据，状态码为 200。

{
  "data": {
    "status": "success",
    "msg": "report event success"
  },
  "code": 0,
  "message": "success"
}

注意事项

1. 请确保在用户实际点击广告时才调用此 API。
2. 不要重复上报同一次点击事件。
3. 如果遇到网络问题导致上报失败，可以在短时间内重试，但不要过度重试。
4. telegramUserId 应该是用户的唯一 Telegram ID，不要使用其他标识符。
5. adId 和 campaignId 应该与用户实际点击的广告相对应，不要使用其他广告的 ID。