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

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
- https://github.com/DMTP-Protocol/sdk-sample-javascript
React
- https://github.com/DMTP-Protocol/sdk-sample-reactjs
Next.js
- https://github.com/DMTP-Protocol/sdk-sample-nextjs-approuter

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 Started Next3. For Publishers

Last updated 10 months ago

Table of Contents

Overview

Vanilla JavaScript Implementation

1. Include Required Scripts

2. Initialize the SDK

3. Add Offer Wall Button

React Implementation

1. SDK Integration

2. Offer Wall Button Component

Next.js Implementation

1. Create BecScript Component

2. Add to Layout

Common Features

Style Configuration

Ad Blacklist Configuration

Ad Click Event Tracking

User Conversion Tracking

API Reference

User Conversion API Response

Function Reference

Event Reference