4.2 API Reference - Reporting Challenge Completion

This section describes the API endpoints for advertisers to report and retrieve information about completed tasks (challenges) by users who have joined their game through the Apps Network. These endpoints are crucial for tracking conversions, updating user rewards, and maintaining the integrity of the points economy.

Search Events

GET /banners/events

This endpoint allows advertisers to retrieve event data for completed challenges or actions within their game.

Parameters

• wa (string, required): The wallet address of the advertiser.

• tui (string, required): The Telegram User ID of the user, for Telegram Mini App environments.

• offset (number, required): The number of items to skip before starting to collect the result set.

• limit (number, required): The maximum number of items to return.

Response

{
  "items": [
    {
      "click_id": "string",
      "action": "string",
      "tui": "string",
      "time": 0,
      "ads_id": "string"
    }
  ]
}

Example:

{
  "items": [
    {
      "click_id": "MCgpUiNoLaprIMULzTCMb",
      "action": "CLICK",
      "tui": "7041114556",
      "time": 1730185746103,
      "ads_id": "67162a0727ccf8b66d89054d"
    },
    {
      "click_id": "968bln0rqkSVJRJLeJUDl",
      "action": "PLAY",
      "tui": "7041114556",
      "time": 1730187267166,
      "ads_id": "671661a627ccf8b66d890951"
    }
  ]
}

• action is either CLICK or PLAY

The events data is cached for 3 days and then reset. However it is recommended to track the user rewards at the advertiser's backend (by tui) to make sure each user is rewarded only once.

Report Event

POST /banners/events

This endpoint is used to report completed tasks (challenges) by users who have joined an advertiser's game.

Request Body

{
  "click_id": "EqTvizvRa4jgQp0FhP4JY",
  "action": "PLAY",
  "tui": "123456789"
}

• click_id (string, required): The unique identifier for the click that brought the user to the game.

• action (string, required): The type of action completed. Currently, use "PLAY" for all completed challenges.

• tui (string, optional): The Telegram User ID of the user, for Telegram Mini App environments.

Response

A successful request returns a 200 OK status code.

API Authentication Using the TMA's Bot Token

The Apps Network offers an optional but recommended authentication system for Telegram Mini App (TMA) advertisers that eliminates the need for complex user registration processes. By sharing your bot token with Apps Network, you enable automatic authentication of all users interacting with your TMA through their existing Telegram credentials.

How to Share Your Bot Token

If you already have a Telegram Mini App with an associated bot, retrieving and sharing your bot token is straightforward. Simply open the BotFather chat in Telegram where your bot was originally created, send the /mybots command to view your existing bots, select the bot associated with your TMA, and choose the "API Token" option to view your bot token. Once you have this token, you can enter it in your Apps Network task details to enable the authentication system. The process requires no changes to your existing API calls or frontend code.

Security and Control

Your bot token is stored securely on the Apps Network backend and is never exposed to frontend code or users. You maintain complete control over the authentication system and can revoke or reset your bot token at any time through BotFather if needed, which will immediately disable authentication through Apps Network. While providing a bot token is optional, including it significantly enhances security by ensuring that API requests are properly authenticated. If you choose not to provide a bot token, the system will still function normally but with reduced security verification.

Usage Notes

1. The click events are reported automatically by the Apps Network, while the play events should be reported by the advertiser's app.

2. Call the POST endpoint when a user completes a significant action or challenge within your game.

3. Include the tui (Telegram User ID) for Telegram Mini App environments.

4. Call the POST endpoint server-side to ensure the security of the reported events.

5. Use the GET endpoint to retrieve and analyze event data as needed.

Accurately reporting completed challenges helps maintain the fairness and effectiveness of the Apps Network ecosystem, ensuring appropriate rewards for quality traffic.