API Ad Integration
If you want to seamlessly integrate ads into your application without obvious pop-ups or banners, you can achieve it through API.
Warning
This method involves a high integration cost. Please use it cautiously and consider using SDK ad integration whenever possible.
This feature is currently in the testing phase, available to a select group of users, and may be removed in future versions.
Tips
Ensure to perform ad retrieval and reporting on the frontend, so the system can access the visiting user's IP for ad region matching.
Prerequisites
- Decide where to display the ads. If unsure, check the ad integration examples.
- Obtain a BlockId. If you don't have one, refer to Get BlockId.
1. Retrieve Ad API
API Description
This API is used to obtain ad information, which you need to embed into your product.
Tips
In the production environment, an ad will not be shown again to a user within 10 minutes after a click.
This restriction does not apply in test environments.
Tips
It is recommended to fetch multiple ads at once and display them simultaneously to improve click-through rates.
Request Method
GET https://app.ton.ai/api/v2/openapi/matching/ad
Request Parameters
Parameter Name | Location | Type | Required | Description |
---|---|---|---|---|
adBlockId | query | string | Yes | Ad spot ID, obtained from Platform -> Ad Spot -> ID |
openId | query | string | Yes | User's unique identifier |
type | query | string | Yes | Type corresponding to openId, currently only 'telegram' |
limit | query | number | Yes | Limit on number of ads returned at once, must be >0 and <10 |
x-api-key | header | string | Yes | API Key, How to Get App Key? |
debug | header | boolean | No | Returns test ads when debug=true, default is false |
Tips
Set debug=false in the production environment.
Response Parsing
Parameter Name | Type | Description |
---|---|---|
adBlockId | string | Ad spot ID |
adId | string | Advertisement ID |
campaignId | string | Campaign ID |
icon | string | Advertisement icon URL |
image | string | Advertisement image URL |
text | string | Advertisement text |
destination | object | Advertisement target information |
destination.actionType | string | Advertisement action type, e.g., 'visit.website' |
destination.url | string | Advertisement target URL |
Complete Request Example
Execute the following request:
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'
A successful response will return a list of ads with a status code of 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. Report Click Event API
API Description
This API is used to report a Click event whenever a user interacts with an ad. Publishers need to call this API when a user clicks an ad.
Warning
Do not report fake Click events
Both advertiser and publisher data are reported to the Ton AI platform. Reporting false Click events will result in data discrepancies, and such behavior will lead to penalties.
Request Method
POST https://app.ton.ai/api/v2/openapi/ad/event/report
Request Parameters
Request parameters should be in JSON format, containing the following fields:
Field Name | Type | Required | Description |
---|---|---|---|
eventType | string | Yes | Event type, fixed value "click" |
eventData | object | Yes | Event data, containing fields |
The eventData
object includes:
Field Name | Type | Required | Description |
---|---|---|---|
adBlockId | string | Yes | Ad spot ID, obtained from Platform -> Ad Spot -> ID |
telegramUserId | string | Yes | User's unique Telegram ID |
adId | string | Yes | Ad ID returned by the previous API, representing the clicked advertisement |
campaignId | string | Yes | Campaign ID of the clicked advertisement |
Complete Request Example
Execute the following request:
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"
}
}
'
A successful response will return the ad list data, with a status code of 200.
{
"data": {
"status": "success",
"msg": "report event success"
},
"code": 0,
"message": "success"
}
Points to Note
- Only call this API when a user actually clicks on an ad.
- Avoid double-reporting the same click event.
- Retry shortly if network issues cause failure, but don’t overdo it.
telegramUserId
should uniquely identify the user on Telegram; do not use other identifiers.adId
andcampaignId
should correspond to the actual clicked ad, not other ads.