> For the complete documentation index, see [llms.txt](https://dmtp.gitbook.io/dmtp-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dmtp.gitbook.io/dmtp-sdk/02-web3-traffic-exchange-getting-started/quick-start-guide.md).

# 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](/dmtp-sdk/03-web3-traffic-exchange-for-publishers.md) and [4. For Advertisers](/dmtp-sdk/04-web3-traffic-exchange-for-advertisers.md)

### Table of Contents

* [Overview](#overview)
* [Vanilla JavaScript Implementation](#vanilla-javascript-implementation)
* [React Implementation](#react-implementation)
* [Next.js Implementation](#react-implementation)
* [Common Features](#common-features)
* [API Reference](#api-reference)

### 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:

```html
<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

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

#### 3. Add Offer Wall Button

```html
<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:

```jsx
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

```jsx
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`:

```typescript
'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`:

```typescript
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:

```javascript
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:

```javascript
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:

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

#### User Conversion Tracking

Check user conversions using the API:

```javascript
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

```json
{
    "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 |
