Documentation pour LLMs
md
# 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)