Quick Start Guide

quick start guide with minimum required snippets and minimum API reference

This is a quick start guide, for the detailed information, please refer 3. For Publishers and 4. For Advertisers

Table of Contents

Overview

The TMA (Telegram Mini App) SDK allows you to integrate advertising functionality into your Telegram Mini App. This guide covers implementation across three different frameworks:

Vanilla JavaScript Implementation

1. Include Required Scripts

Add the following to your HTML <head> section:

<script src="https://bec.apps-network.net/latest/bec.js?walletAddress=YOUR_WALLET_ADDRESS"></script>
<script src="https://telegram.org/js/telegram-web-app.js"></script>

Find your hashed wallet address in the Snippets seciton of the web app.

2. Initialize the SDK

if (TE && typeof TE.onLoad === 'function') {
    TE.onLoad()
} else {
    console.error('SDK not loaded');
}

3. Add Offer Wall Button

<button id="openOfferWallButton">Open Offer Wall</button>
<script>
    document.addEventListener('DOMContentLoaded', function() {
        const openOfferWallButton = document.getElementById('openOfferWallButton');
        openOfferWallButton.addEventListener('click', function() {
            if (TE && typeof TE.offerWall === 'function') {
                TE.offerWall();
            } else {
                console.error('SDK not initialized');
            }
        });
    });
</script>

React Implementation

1. SDK Integration

Create a component to handle SDK initialization:

import { useEffect } from 'react';

function TMASDKProvider({ children }) {
    useEffect(() => {
        if (TE && typeof TE.onLoad === 'function') {
            TE.onLoad()
        } else {
            console.error('onLoad is not a function');
        }
    }, []);

    return <>{children}</>;
}

2. Offer Wall Button Component

const OfferWallButton = () => {
    return (
        <button 
            onClick={() => {
                if (TE && typeof TE.offerWall === 'function') {
                    TE.offerWall();
                } else {
                    console.error('TE is not defined or offerWall is not a function');
                }
            }}
        >
            Open Offer Wall
        </button>
    );
};

Next.js Implementation

1. Create BecScript Component

Create a new file components/BecScript.tsx:

'use client';
import Script from "next/script";

declare const TE: any;

export default function BecScript() {
    return (
        <Script
            src="https://bec.apps-network.net/latest/bec.js?walletAddress=YOUR_WALLET_ADDRESS"
            strategy="afterInteractive"
            onLoad={() => {
                if (typeof TE.onLoad === "function") {
                    TE.onLoad();
                } else {
                    console.error('TE.onLoad is not a function');
                }
            }}
        />
    );
}

2. Add to Layout

In your app/layout.tsx:

import BecScript from '@/components/BecScript';

export default function RootLayout({
    children,
}: {
    children: React.ReactNode;
}) {
    return (
        <html lang="en">
            <body>
                {children}
                <BecScript />
            </body>
        </html>
    );
}

Common Features

Style Configuration

Configure the appearance of your offer wall:

useEffect(() => {
    document.addEventListener('becLoaded', function (event) {
        TE.configureOfferWallStyle({
            topBar: {
                backgroundColor: '#2c3e50',
                textColor: '#ecf0f1'
            },
            content: {
                backgroundColor: '#34495e',
                appNameColor: '#ecf0f1',
                appDescriptionColor: '#bdc3c7'
            },
            button: {
                backgroundColor: '#3498db',
                textColor: '#ffffff',
                highlightedBackgroundColor: '#2980b9',
                highlightedTextColor: '#ffffff',
                outlineColor: '#3498db'
            }
        });
    });
}, []);

Ad Blacklist Configuration

Block specific ads from appearing:

useEffect(() => {
    document.addEventListener('becLoaded', function (event) {
        if (TE && typeof TE.setBlacklistAds === 'function') {
            TE.setBlacklistAds([
                'SEED App - Mine SEED', // ad name
                '66ec39da467ed0b3fdea3539', // ad id
            ]);
        }
    });
}, []);

Ad Click Event Tracking

Monitor when users interact with ads:

useEffect(() => {
    document.addEventListener('TEAdClicked', function (event) {
        const adInfo = event?.detail;
        console.log('TEAdClicked', adInfo);
    });
}, []);

User Conversion Tracking

Check user conversions using the API:

async function checkUserConversion() {
    const telegram_user_id = getTelegramUserId();
    const url = `https://click.apps-network.net/banners/events?wa=YOUR_WALLET_ADDRESS&offset=0&limit=10&tui=${telegram_user_id}`;
    const response = await fetch(url);
    const data = await response.json();
    return data;
}

API Reference

User Conversion API Response

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

Function Reference

Function
Description
Parameters

TE.onLoad()

Initializes the SDK

None

TE.offerWall()

Opens the offer wall

None

TE.configureOfferWallStyle()

Configures the offer wall appearance

StyleConfig object

TE.setBlacklistAds()

Sets the ad blacklist

Array of ad IDs or names

Event Reference

Event
Description
Event Data

becLoaded

Fired when SDK is loaded

None

TEAdClicked

Fired when an ad is clicked

Ad details in event.detail

Previous2. Getting StartedNext3. For Publishers

Last updated