用户画像与精准投放

更高的收益

通过用户画像，流量主可以更清晰地了解自己流量的特征，从而吸引更高价值的广告主。精准投放的好处包括：

提升广告收益：广告主可以根据用户画像进行更有针对性的广告投放。例如，广告主指定投放给 Wallet user 时，单价通常是无条件广告的 8 倍左右。
优化广告策略：通过分析用户画像，流量主可以调整广告策略，提高广告点击率和转化率。
增强用户体验：精准的广告投放可以减少对用户的打扰，提供更相关的广告内容。

提示

如果广告主对受众有特定要求，例如，只投放给 Wallet user，未对接用户画像的流量主，将无法承接此类广告

上报方式

为了实现精准投放，流量主需要将用户画像数据上报到 Ads3 平台。上报方式包括增量上报和存量上报两种。

增量上报

增量上报通过 SDK 实现，在用户完成 Wallet Connect 后执行

import { UpdateUserProfile } from 'ton-ai-sdk'

useEffect(() => {
  const data = await UpdateUserProfile({
    telegramUserId: '17***809', // 可选项，当前的用户 telegram user id，如果不传，SDK会尝试自动获取
    walletAddress: 'UQCDBE***85m4v', // 用户的钱包地址
    walletClassify: 'ton', // 当提供 walletAddress 时必选，用户钱包地址的类型，目前支持 ton,evm
  })
  console.log('UpdateUserProfile:', data)
}, [])

提示

用户画像不会立即生效，需要等待 1-2 天

存量上报

存量上报适用于已有大量用户数据的场景，支持 API 和 CSV 导入两种方式。

CSV 导入

通过上传 CSV 文件的方式批量导入用户画像数据。适合数据量较大且需要一次性导入的场景。

操作简单：只需按照模板格式准备数据文件并上传。
高效便捷：适合一次性处理大量数据。

CSV 文件模板：

telegramUserId,walletAddress,walletClassify
123456789,0xAbC123456789DefG,ton
987654321,0xDeF987654321AbC,evm
456789123,0x123456789AbCDef,ton
321654987,0x987654321DefAbC,evm
654321789,0x456789123DefAbC,ton

API 批量上报

通过调用 Ads3 提供的 API 接口，将用户画像数据批量上传。适合开发能力较强的团队。

灵活性高：API 支持自定义字段，满足不同业务需求。
自动化：可与现有系统集成，实现自动化数据上传。

服务 Host 地址

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

正式环境：https://app.ton.ai/

接口描述

此 API 用于批量提交用户画像数据，以提供更准确和有效的广告投放。该接口支持一次性提交多个用户的画像数据。

提示

为获得最佳性能，请每次上传不超过 5000 条记录。

请求方法

POST /api/v2/openapi/user/profile/batch

请求参数

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

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

字段名	类型	必填	描述
list	array	是	用户画像数据数组，最少 1 条，最多 5000 条

list 数组中的每个对象包含以下字段：

字段名	类型	必填	描述
telegramUserId	string	是	用户的唯一 Telegram ID
ipAddress	string	否	用户的 IP 地址
walletAddress	string	否	用户的钱包地址
walletClassify	string	否	用户钱包地址的类型，支持 ton、evm、solana

完整请求示例

发起请求：

curl --request POST \
     --url https://staging.ton.ai/api/v2/openapi/user/profile/batch \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: moJHPwHiGpSP7Lrz88xY1IAXXamF90' \
     --data '
{
  "list": [
    {
      "telegramUserId": "1621364061",
      "ipAddress": "137.184.166.75",
      "walletAddress": "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs",
      "walletClassify": "ton"
    },
    {
      "telegramUserId": "987654321",
      "walletAddress": "0xDeF987654321AbC",
      "walletClassify": "evm"
    },
    {
      "telegramUserId": "123456789",
    }
  ]
}
'

成功响应会返回处理结果，状态码为 200。

{
  "code": 0,
  "message": "success"
}

注意事项

请确保提供的 telegramUserId 是真实有效的，这是唯一必填字段。
如果提供了 walletAddress，建议同时提供对应的 walletClassify。
walletClassify 目前支持三种类型：ton、evm 和 solana。
ipAddress 字段为可选，如果提供，请确保是有效的 IP 地址格式。
批量上传时，请控制每次请求的数据量，最少 1 条，最多 5000 条记录。
如果遇到网络问题导致上报失败，可以在短时间内重试，但不要过度重试。

查看用户画像

提示

Coming Soon

查看用户 Wallet 资产的分层情况

还有查看用户地区分布， Premium 用户占比等信息