Registration
Before using advertising features, please complete registration.
Create Platform
A Platform represents your APP or Website.
- App name: The name of your APP.
- Telegram direct link: The direct link to your Telegram application.
- Web app url: The URL of your application.
Info
App owners can use the /myapps command in BotFather to get the Telegram direct link.
Create Block
A Block represents an ad space. You can create multiple Blocks to compare the effectiveness at different placements.
- Name: The name of the Block.
- Reward Webhook URL: When a user clicks on an ad (and the ad system receives the click), Ads3 will send a request to this URL where you can implement reward distribution.
Tips
If you want to show multiple ads on your website, we recommend creating multiple Blocks to compare each Block's conversion effects.
Moderation
Each Platform requires moderation by Ads3. Only after approval can it become a traffic source for Ads3.
Tips
Before approval, you can only get test ads. After moderation, you can access live ads.
Get BlockId
On the Platform details page, you can view information for each Block. There's a column with BlockId and a copy button next to it; click to copy.
Reward Webhook
When a user clicks on an ad (and the ad system receives the click), Ads3 sends a request to this URL for reward distribution.
Request Method
POST
Request Parameters
| Parameter Name | Position | Type | Description |
|---|---|---|---|
| adBlockId | body | string | Ad space ID, located in Platform -> Block -> ID |
| openId | body | string | User's unique ID, e.g., telegramUserId |
| type | body | string | Type corresponding to openId, currently supports 'telegram' |
| campaignId | body | string | Campaign ID, recommended for idempotency when issuing rewards |
| x-api-key | header | string | Your account's App Key, validate this Key to prevent forgery |
| eventType | body | string | Event type, supports click, complete, conversion |
| eventId | body | string | Event ID |
| isSupportVerified | body | boolean | Indicates if the current campaign supports strong verification, true means it does |
| uuid | body | string | Device fingerprint |
Note, the value of eventType can be:
- click: User clicked on the ad (Note: triggering a click event won't proceed with a complete event)
- complete: User watched 15 seconds of the ad (did not click)
- conversion: User visited the advertiser's page (usually, you can ignore this event)
You can decide which type of event to use to issue a reward based on your product needs.
If a user should be rewarded after watching the ad, the logic is:
if (eventType === 'complete' || eventType === 'click') {
// Issue reward
}If a user must click the ad to get a reward, the logic is:
if (eventType === 'click') {
// Issue reward
}Attention
- The system might request the Reward Webhook multiple times; ensure your logic is idempotent, using eventId for idempotency.
- Validate the App Key to prevent forgery.