API 广告集成

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

注意

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

此功能目前处于测试阶段，只对部分用户开放

前置要求

• 知道在什么地方展示广告，如果没有，请先查看 Ad integration examples
• 已经获取了 ExchangeId，如果没有，请先查看 Get ExchangeId

服务 Host 地址

测试环境：https://staging.ton.ai/

生产环境：https://app.ton.ai/

1. 获取广告 API

接口描述

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

提示

在生产环境中，用户点击过的广告不会再次被推荐。测试环境中此功能未启用。

提示

建议一次性获取多个广告，让用户可以有更多选择，提高用户的点击率。

请求方法

GET /api/v2/openapi/matching/exchange

请求参数

参数名	位置	类型	必填	描述
exchangeCampaignId	query	string	是	交易所广告活动 ID，从管理后台的交易所 -> ID 获取
openId	query	string	是	用户的唯一标识
type	query	string	是	用户类型，目前仅支持 'telegram'
limit	query	number	是	一次性返回广告数量限制，必须大于 0 且小于 10
x-api-key	header	string	是	如何获取 APP Key?

返回参数

字段名	类型	必填	描述
inExchangeCampaignId	string	是	流量导入方
outExchangeCampaignId	string	是	流量导出方
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/exchange?exchangeCampaignId=66f65ed42ec147ec042aa597&openId=16213622061&type=telegram&limit=2' \
     --header 'accept: application/json' \
     --header 'x-api-key: moJHPwHiGpSP7Lrz88xY1IAXXamF90'

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

{
  "data": {
    "success": true,
    "exchangeCampaigns": [
      {
        "icon": "https://file.pea.ai/ad_avatar_development/665448d46c9e4700110b1b44_131267_TonAi-black%20bg%20logo-80.jpg",
        "inExchangeCampaignId": "66f65d2d2ec147ec042aa504",
        "outExchangeCampaignId": "66f65ed42ec147ec042aa597",
        "image": "https://file.pea.ai/ad_development/665448d46c9e4700110b1b44_437882_image%20%281%29.png",
        "text": "Welcome to Ads3",
        "destination": {
          "actionType": "visit.website",
          "url": "https://t.me/peaaibot/app"
        }
      },
      {
        "icon": "https://file.pea.ai/ad_avatar_development/66f8f1f363476d0011ed93c3_470779_1111.png",
        "inExchangeCampaignId": "66f8f68d1d2a179b00c0823e",
        "outExchangeCampaignId": "66f65ed42ec147ec042aa597",
        "text": "Click to Earn Bankcoins",
        "destination": {
          "actionType": "visit.website",
          "url": "https://t.me/bankcoins_bot/start?startapp=source-tonai"
        }
      }
    ]
  },
  "code": 0,
  "message": "success"
}

2. 上报 Click 事件 API

接口描述

此 API 用于在用户点击广告时上报 Click 事件。合作方需要在用户点击广告时调用此接口。

注意

请勿上报虚假的 Click 事件

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

请求方法

POST /api/v2/openapi/exchange/event/report

请求参数

参数名	位置	类型	必填	描述
x-api-key	header	string	是	如何获取 APP Key?

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

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

eventData 对象包含以下字段：

字段名	类型	必填	描述
telegramUserId	string	是	用户的唯一 Telegram ID
inExchangeCampaignId	string	是	流量导入方 ID
outExchangeCampaignId	string	是	流量导出方 ID

完整请求示例

发起请求：

curl --request POST \
     --url https://staging.ton.ai/api/v2/openapi/exchange/event/report \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: moJHPwHiGpSP7Lrz88xY1IAXXamF90' \
     --data '
{
  "eventType": "click",
  "eventData": {
    "telegramUserId": "1728125519",
    "inExchangeCampaignId": "66f50be715d2076bd74c7452",
    "outExchangeCampaignId": "66f3969f7fe5f0572809261a"
  }
}
'

成功响应会返回上传成功的状态，状态码为 200。

{
  "status": "success"
}

注意事项

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