Документация для LLMs

# Adsgram SDK LLM Integration Guide
## Overview

The SDK provides two banner formats:
- **Reward/Interstitial** - fullscreen post and video banners
- **Task** - native task-completion format (subscribe to channel, open mini-app)

## Installation

### Option 1: Script Tag (Recommended for LLM)

```html
<script src="https://sad.adsgram.ai/js/sad.min.js"></script>
```

### Option 2: NPM Packages

```bash
npm install @adsgram/react  # React: https://www.npmjs.com/package/@adsgram/react
npm install @adsgram/vue    # Vue: https://www.npmjs.com/package/@adsgram/vue
```

## Initialization

### Reward and Interstitial Formats

```javascript
const AdController = window.Adsgram.init({
  blockId: "your-block-id",  // required
  debug: false,               // optional, for testing
});
```

> **Important**: Initialization is only required for Reward and Interstitial formats. For Task format, initialization is not needed.

### Task Format

Task is implemented as a web component `<adsgram-task>`:

```html
<adsgram-task block-id="task-your-block-id" debug="false"></adsgram-task>
```

Attributes:
- `block-id` (required) - block ID from your account (format: `task-xxx`)
- `debug` (optional) - debug mode
- `classname` (optional) - CSS class for container

## Showing Banners

### Reward/Interstitial

```javascript
// Using promises
AdController.show()
  .then((result) => {
    // user watched till the end
    // give reward
  })
  .catch((result) => {
    // error or skip
  });

// Using async/await
try {
  const result = await AdController.show();
  // user watched till the end
} catch (result) {
  // error or skip
}
```

### Task (via web component)

```javascript
const taskElement = document.querySelector('adsgram-task');

// Subscribe to events
taskElement.addEventListener('reward', (event) => {
  // user completed the task
});

taskElement.addEventListener('onBannerNotFound', (event) => {
  // no banner available
});

taskElement.addEventListener('onError', (event) => {
  // loading error
});

taskElement.addEventListener('onTooLongSession', (event) => {
  // session too long
});
```

## Events

### Reward/Interstitial Events

Subscribe to events for more control:

```javascript
AdController.addEventListener('onStart', () => {});
AdController.addEventListener('onSkip', () => {});
AdController.addEventListener('onReward', () => {});
AdController.addEventListener('onComplete', () => {});
AdController.addEventListener('onError', () => {});
AdController.addEventListener('onBannerNotFound', () => {});
AdController.addEventListener('onNonStopShow', () => {});
AdController.addEventListener('onTooLongSession', () => {});
```

| Event | Description |
|-------|-------------|
| `onStart` | Banner frame is shown |
| `onSkip` | User closed the ad |
| `onReward` | User watched rewarded ad to the end |
| `onComplete` | User watched interstitial to the end or closed it |
| `onError` | Error during render or playback |
| `onBannerNotFound` | No banner to display |
| `onNonStopShow` | User trying to watch multiple ads in a row |
| `onTooLongSession` | Session is too long, restart the app |

### Task Events

| Event | Description |
|-------|-------------|
| `reward` | User completed the task |
| `onBannerNotFound` | No banner available |
| `onError` | Loading/playback error |
| `onTooLongSession` | Session is too long |

## Task Customization

### Slots

Use slots to customize the task appearance:

```html
<adsgram-task block-id="task-123" class="my-task">
  <div slot="reward" class="my-reward">Your reward: 100 coins</div>
  <button slot="button" class="my-button">Complete Task</button>
  <div slot="claim" class="my-claim">Claim Reward</div>
  <div slot="done" class="my-done">Task Completed!</div>
</adsgram-task>
```

| Slot | Description |
|------|-------------|
| `reward` | Displays after task completion |
| `button` | Button to start/complete the task |
| `claim` | Shown after clicking the button |
| `done` | Shown after receiving the reward |

### CSS Variables

```css
.my-task {
  --adsgram-task-font-size: 16px; /* min 14px */
  --adsgram-task-icon-size: 50px; /* min 30px */
  --adsgram-task-icon-title-gap: 15px; /* min 5px max 40px */
  --adsgram-task-button-width: 60px; /* min 40px */
  --adsgram-task-icon-border-radius: 8px;
}
```

## API Reference

### AdController Methods

| Method | Description |
|--------|-------------|
| `show()` | Loads and shows the banner |
| `destroy()` | Stops banner and cleans up memory |
| `addEventListener(event, callback)` | Subscribe to events |
| `removeEventListener(event, callback)` | Unsubscribe from events |

### Initialization Parameters

```typescript
interface InitParams {
  blockId: string;        // block ID (required)
  debug?: boolean;        // test mode
  debugConsole?: boolean; // console logs
  debugBannerType?: "FullscreenMedia" | "RewardedVideo";
}
```

## Getting blockId

1. Register at [partner dashboard](https://partner.adsgram.ai)
2. Create a block in the interface
3. Copy the ID from block settings

> **Note**: Task blockId must be in format `task-xxx`. Only one Task block is allowed per account.

### BlockId Format

| Block Type | Format | Example |
|------------|--------|---------|
| Reward | Numeric | `"123"` |
| Interstitial | `int-xxx` | `"int-456"` |
| Task | `task-xxx` | `"task-789"` |

## Debug Mode

Enable for testing:

```javascript
const AdController = window.Adsgram.init({
  blockId: "your-block-id",
  debug: true,
  debugConsole: true,
});
```

> Warning: Remember to disable `debug` before production!

## Usage Examples

### Basic Example (Vanilla JS)

```html
<script src="https://sad.adsgram.ai/js/sad.min.js"></script>
<button id="showAd">Show Ad</button>

<script>
const ad = window.Adsgram.init({ blockId: "123" });
document.getElementById('showAd').addEventListener('click', () => {
  ad.show().then(() => console.log('Watched'));
});
</script>
```

### Task Web Component (Vanilla JS)

```html
<adsgram-task block-id="task-123" id="task-banner"></adsgram-task>

<script>
document.querySelector('#task-banner').addEventListener('reward', () => {
  console.log('Task completed!');
});
</script>
```

### React

```jsx
import { useEffect, useRef } from 'react';

// Hook for Reward/Interstitial
function useAdsgram(blockId, debug = false) {
  const adControllerRef = useRef(null);
  
  useEffect(() => {
    adControllerRef.current = window.Adsgram.init({ blockId, debug });
    return () => {
      adControllerRef.current?.destroy();
    };
  }, [blockId]);
  
  return adControllerRef.current;
}

// Usage
function AdButton({ blockId }) {
  const ad = useAdsgram(blockId);
  
  return (
    <button onClick={() => ad?.show()}>
      Show Ad
    </button>
  );
}

// Task with slots
function TaskBanner({ blockId, onReward }) {
  useEffect(() => {
    const taskEl = document.querySelector('adsgram-task');
    taskEl?.addEventListener('reward', onReward);
    return () => taskEl?.removeEventListener('reward', onReward);
  }, [onReward]);
  
  return (
    <adsgram-task block-id={blockId}>
      <div slot="reward" style={{ color: 'green' }}>
        🎁 Reward Unlocked!
      </div>
      <button slot="button" style={{ padding: '10px 20px' }}>
        Complete Task
      </button>
    </adsgram-task>
  );
}
```

## Links

- [Official Documentation](https://docs.adsgram.ai/publisher/)
- [React Package](https://www.npmjs.com/package/@adsgram/react)
- [Vue Package](https://www.npmjs.com/package/@adsgram/vue)