API Reference

Exchange 换量对接

Ton AI 换量功能优势

  • 全面数据洞察：通过详细的统计数据，全面了解换量情况，优化广告策略。
  • 公平策略：使用配额（Quota）平衡导入和导出的用户数量。
  • 高效用户管理：基于大数据能力，自动过滤重复用户，确保历史导流用户不会再次导流。

注册

在使用换量功能之前，请先完成注册。注册成功后，您将能够访问所有换量功能。

创建 Exchange 任务

在“Exchanges”页面，点击右上角的“Create Exchange”。

  1. 填写“Exchange Name”
  2. 填写“Destination”，这是用户的落地页面，可以填写小程序的访问链接，或选择 Telegram 群组/频道
  3. 填写广告创意：
    • 广告文案，建议使用吸引力强的文案，50字以内
    • Banner，图片比例为 5:1，用于其他合作方展示广告
    • Icon，用于其他合作方展示广告

点击保存，即可成功创建 Exchange 任务。

Exchange 任务示例

流量导出

您需要在产品中嵌入广告来导出流量，从而获得配额（Quota）。有了配额，其他合作方的流量（用户）也将以广告形式流入您的产品中。


您查看 Exchange 任务的“User out”数据统计，显示累计导出用户数量。

数据统计

Ton AI 以 CPC 口径统计换量，您 APP 的用户每次点击广告，“User out”版块的 Clicks 数据和 Earn (Quota) 将会 +1。


Ton AI 提供两种广告嵌入方式，您可以根据产品类型选择合适的方式。

方案1：无缝嵌入产品

这种嵌入方式对接成本稍高，但是用户体验非常好。

Ton AI 开放了两个 API：

API 获取换量广告

可以获得一至多个换量广告信息，您需要将广告信息嵌入到您的产品中

关键参数：

  • exchangeCampaignId 在管理后台创建的 ExchangeId，从这里复制，见下图
  • telegramUserId 当前 Telegram用户的 ID

返回值：一至多个广告信息，您需要将广告展示在您的产品上

API 文档中有详细的字段描述


API 上报 Click 事件

用户点击广告时，上报事件

关键参数：

  • inExchangeCampaignId 从哪个合作方过来的用户，从广告信息中获取
  • outExchangeCampaignId 跳转到哪个合作方，从广告信息中获取

广告效果

使用这种方式，您可以将广告嵌入产品中的任意位置，例如包装成任务放到任务列表里，用奖励驱动用户去点击广告。

广告效果示例：

嵌入效果展示

注意事项

如果您需要配置多个广告位置，建议每个广告位置都配置同一个 ExchangeId，而不是创建多个 Exchange。


请勿上报虚假的 Click 事件

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


方案2：Banner 广告

这种嵌入方式对接成本低，但是用户体验较差，转化效果也不太好。

请先根据 安装 SDK 指引完成 SDK 安装，然后，导入必要的 SDK 组件：

import { TonExchangeBanner } from 'ton-ai-sdk';
import 'ton-ai-sdk/dist/index.css';

在您的小程序中选好展示 Banner 的位置，确保广告位的宽高比为 5:1，例如 400x80，在对应的 HTML 中嵌入 TonExchangeBanner 组件：

注意：EXCHANGE_ID 是您在管理控制台中创建的 Exchange 任务的 ID，可以从那里复制。

<div>
  <!-- 您要嵌入 SDK 的 div -->
  <TonExchangeBanner exchangeId={exchangeId}></TonExchangeBanner>
</div>

SDK 会自动拉取适合当前用户的广告，并自动上报 Click 事件到 Ton AI。

广告效果展示：

效果展示

流量导入

当您的配额（Quota）充足时，其他合作方将展示您的广告，流量将陆续导入到您的产品中。

在 Ton AI 管理后台，您可以查看 Exchange 任务的“User In”数据统计，显示为您带来的用户数量。

当配额消耗完后，系统将自动停止流量导入，您需要导出更多用户来获取更多配额。

数据统计

Ton AI 以 CPC 口径统计换量，其他合作方的用户每次点击您的广告，将消耗 1 配额（Quota）。

Conversion （新用户）统计

项目方都希望能通过换量获取新用户，为了得到更好的换量效果，您需要将新用户上报给 Ton AI，Ton AI 称之为 Conversion 事件。

在前端调用 SDK ：

import { SendTonExchangeConversion } from 'ton-ai-sdk';

SendTonExchangeConversion(exchangeId: string);

SDK 会自动获取当前用户的 TelegramUserId，然后上报 Conversion 事件。

Conversion 很重要

  • 系统会根据 Conversion 用户的特征推荐更合适的用户
  • 有了 Conversion 数据，系统会计算每个合作方导入流量的转化率（CR = Conversions / Clicks），CR 高的合作方将得到更高的曝光优先级。

Quota 配额控制

当 Quota 下降到 0 时，Exchange 进入暂停状态，用户将不会继续导入，但是用户导出会继续。

当 Quota 恢复到 100 时，Exchange 恢复到 Ongoing 状态，用户导入也会恢复


测试环境每个账户将会获得 1000 Quota 用于测试