# Quick Start Guide

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 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dmtp.gitbook.io/dmtp-sdk/02-web3-traffic-exchange-getting-started/quick-start-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
