### AdsGram SDK Installation
Source: https://docs.adsgram.ai/publisher/reward-interstitial-integration
Instructions for installing the AdsGram SDK, either by inserting a script tag or using npm for React and Vue projects.
```APIDOC
## AdsGram SDK Installation
### Description
Instructions for installing the AdsGram SDK, either by inserting a script tag or using npm for React and Vue projects.
### Method
**Script Insertion**
### Endpoint
Insert the following script tag into the `` section of your HTML file:
```html
```
### Method
**NPM Installation (React/Vue)**
### Endpoint
For React projects:
```bash
npm install @adsgram/react
```
For Vue projects:
```bash
npm install @adsgram/vue
```
```
--------------------------------
### AdsGram Campaign Setup with Keitaro
Source: https://docs.adsgram.ai/advertiser/tracking
Instructions for setting up a campaign in AdsGram using the Click URL generated from Keitaro, including adding necessary macros.
```APIDOC
## AdsGram Campaign Setup with Keitaro
### Description
This guide explains how to configure a campaign within the AdsGram platform by utilizing the Click URL obtained from your Keitaro tracker. It emphasizes the inclusion of essential AdsGram macros for accurate tracking.
### Method
POST (for campaign creation)
### Endpoint
`/campaigns` (example endpoint for creating a campaign)
### Parameters
#### Query Parameters
- **campaign_id** (string) - Required - The unique identifier for the campaign in Keitaro.
- **click_id** (string) - Required - The unique identifier for a click in Keitaro.
- **publisher_id** (string) - Required - The identifier for the publisher.
- **banner_id** (string) - Required - The identifier for the banner.
- **record_data** (string) - Required - Placeholder for conversion data to be sent to AdsGram.
#### Request Body
- **name** (string) - Required - The name of the campaign.
- **click_url** (string) - Required - The tracking link from Keitaro, augmented with AdsGram macros.
### Request Example
```json
{
"name": "My Keitaro Campaign",
"click_url": "https://your-keitaro-domain.com/click.php?campaign_id={campaign_id}&subid={click_id}&publisher={publisher_id}&banner={banner_id}&record={record_data}"
}
```
### Response
#### Success Response (200)
```json
{
"campaign_id": "campaign_abc",
"status": "created",
"tracking_link": "https://adsgram.ai/campaigns/campaign_abc/track"
}
```
#### Error Response (400/404/500)
```json
{
"error": "Invalid request or server error."
}
```
```
--------------------------------
### AdsGram Campaign Setup with Kochava
Source: https://docs.adsgram.ai/advertiser/tracking
Instructions for setting up a campaign in AdsGram using the tracking link generated from Kochava, including adding mandatory AdsGram macros.
```APIDOC
## AdsGram Campaign Setup with Kochava
### Description
This guide details the process of configuring a campaign in AdsGram by using the tracking link generated within Kochava. It highlights the importance of appending the required AdsGram macros to ensure comprehensive data tracking.
### Method
POST (for campaign creation)
### Endpoint
`/campaigns` (example endpoint for creating a campaign)
### Parameters
#### Query Parameters
- **campaign_id** (string) - Required - The unique identifier for the campaign in Kochava.
- **click_id** (string) - Required - The unique identifier for a click in Kochava.
- **publisher_id** (string) - Required - The identifier for the publisher.
- **record_data** (string) - Required - Placeholder for conversion data to be sent to AdsGram.
#### Request Body
- **name** (string) - Required - The name of the campaign.
- **click_url** (string) - Required - The tracking link from Kochava, augmented with AdsGram macros.
### Request Example
```json
{
"name": "My Kochava Campaign",
"click_url": "https://your-app.kochava.com/install?data={encrypted_data}&campaign_id={campaign_id}&click_id={click_id}&publisher_id={publisher_id}&record={record_data}"
}
```
### Response
#### Success Response (200)
```json
{
"campaign_id": "campaign_xyz",
"status": "created",
"tracking_link": "https://adsgram.ai/campaigns/campaign_xyz/track"
}
```
#### Error Response (400/404/500)
```json
{
"error": "Invalid request or server error."
}
```
```
--------------------------------
### React: Show Ad Button Component using useAdsgram Hook
Source: https://docs.adsgram.ai/publisher/reward-interstitial-code-examples
An example React component `ShowAdButton` that utilizes the `useAdsgram` hook to display an ad when a button is clicked. It includes example callbacks for reward and error handling.
```jsx
import { useCallback, ReactElement } from 'react'
import { useAdsgram } from "./hooks/useAdsgram.ts";
export function ShowAdButton() {
const onReward = useCallback(() => {
alert('Reward');
}, []);
const onError = useCallback((result) => {
alert(JSON.stringify(result, null, 4));
}, []);
/**
* insert your-block-id
*/
const showAd = useAdsgram({ blockId: "your-block-id", onReward, onError });
return (
)
}
```
```tsx
import { useCallback, ReactElement } from 'react'
import { useAdsgram } from "./hooks/useAdsgram.ts";
import { ShowPromiseResult } from "./types/adsgram";
export function ShowAdButton(): ReactElement {
const onReward = useCallback(() => {
alert('Reward');
}, []);
const onError = useCallback((result: ShowPromiseResult) => {
alert(JSON.stringify(result, null, 4));
}, []);
/**
* insert your-block-id
*/
const showAd = useAdsgram({ blockId: "your-block-id", onReward, onError });
return (
)
}
```
--------------------------------
### AdsGram Campaign URL Examples
Source: https://docs.adsgram.ai/advertiser/tracking
Examples of campaign URLs with AdsGram macros for tracking performance and attribution. The `{record_data}` macro is essential for API operation and conversion tracking.
```URL
https://your-tracker.com/?campaign={campaign_id}&banner={banner_id}&pub={publisher_id}&clickid={click_id}&record={record_data}
```
```URL
https://t.me/[name_of_the_bot]?start=[unique_referral_link]_{campaign_id}_{banner_id}_{publisher_id}_{click_id}_{record_data}
```
--------------------------------
### AdsGram Conversion Confirmation API Request Example
Source: https://docs.adsgram.ai/advertiser/tracking
Example of a server-side request to the AdsGram API for confirming user conversions. This requires a unique token and the record data from the tracking URL.
```HTTP
https://api.adsgram.ai/confirm_conversion?token=YOUR_UNIQUE_TOKEN&record=7f3a1b6c5d2e4f8a
```
--------------------------------
### Initialize and Show Ad with Vanilla JS
Source: https://docs.adsgram.ai/publisher/reward-interstitial-code-examples
This snippet shows how to initialize the Adsgram AdController with a block ID and display an ad when a button is clicked. It handles both successful ad views and potential errors during ad playback. Dependencies include the Adsgram SDK and the Telegram Web App SDK.
```html
Test app
```
--------------------------------
### Get Ads for Telegram Bot
Source: https://docs.adsgram.ai/bots/block-integration
Send a GET request to this endpoint to retrieve an ad to display in your Telegram bot. You need to provide the Telegram user ID and your Ad Block ID.
```APIDOC
## GET /advbot
### Description
Retrieves an ad to display in your Telegram bot.
### Method
GET
### Endpoint
https://api.adsgram.ai/advbot
### Parameters
#### Query Parameters
- **tgid** (string) - Required - Telegram user ID.
- **blockid** (string) - Required - Your Ad Block ID (from dashboard). Use only the numeric part, without the `bot-` prefix.
- **language** (string) - Optional - Specify the desired language for the ads (e.g., `en`).
### Response
#### Success Response (200)
- **text_html** (string) - The ad content in HTML format.
- **click_url** (string) - The URL to redirect to when the ad is clicked.
- **button_name** (string) - The text for the ad's button.
- **image_url** (string) - The URL of the ad's image.
- **button_reward_name** (string) - The text for a reward button, if applicable.
- **reward_url** (string) - The URL for the reward button, if applicable.
#### Response Example
```json
{
"text_html": "Follow Velo For The Coming Big Announcement\n\nVelo\n\nMiss the Velo X Blackrock announcement previously?\nFollow Velo X now!\n\nClick here to claim the reward after completing task!\nAd. 18+",
"click_url": "https://api.adsgram.ai/short/AwJ8ughbhDH",
"button_name": "Follow us!",
"image_url": "https://images.adsgram.ai/3d618923-ba5f-4589-a3a8-ed97bd301435",
"button_reward_name": "Claim reward!",
"reward_url": "https://api.adsgram.ai/short/DvvpNWxAtaG"
}
```
```
--------------------------------
### Install AdsGram React Package via npm
Source: https://docs.adsgram.ai/publisher/reward-interstitial-integration
Install the AdsGram SDK for React applications using npm. This package provides specific bindings and utilities for seamless integration within a React environment.
```bash
npm install @adsgram/react
```
--------------------------------
### Install AdsGram Vue Package via npm
Source: https://docs.adsgram.ai/publisher/reward-interstitial-integration
Install the AdsGram SDK for Vue applications using npm. This package offers tailored integration for Vue.js projects, simplifying ad implementation.
```bash
npm install @adsgram/vue
```
--------------------------------
### Show Rewarded/Interstitial Ad
Source: https://docs.adsgram.ai/publisher/reward-interstitial-integration
Code examples for displaying Rewarded and Interstitial ads using the AdController.show() method, including promise handling for ad completion or errors.
```APIDOC
## Show Rewarded/Interstitial Ad
### Description
Displays a Rewarded or Interstitial ad. The `show()` method returns a promise that resolves when the ad is watched till the end (Rewarded) or closed (Interstitial), or rejects if an error occurs.
### Method
JavaScript
### Endpoint
```javascript
AdController.show().then((result) => {
// Ad watched till the end or closed (interstitial)
// Reward user for rewarded format
}).catch((result) => {
// User encountered an error during ad playback
// Handle error appropriately
});
```
### Method
TypeScript
### Endpoint
```typescript
AdController.show().then((result: ShowPromiseResult) => {
// Ad watched till the end or closed (interstitial)
// Reward user for rewarded format
}).catch((result: ShowPromiseResult) => {
// User encountered an error during ad playback or skipped the ad
// Handle error appropriately
});
```
### Response
#### Success Response (Promise Resolution)
- **result** (ShowPromiseResult) - An object containing details about the ad event.
```typescript
interface ShowPromiseResult {
done: boolean; // true if ad watched till end or closed (interstitial), false otherwise
description: string; // Event description
state: 'load' | 'render' | 'playing' | 'destroy'; // State of the ad banner
error: boolean; // true if the event was due to an error, false otherwise
}
```
```
--------------------------------
### React: Create useAdsgram Hook for Rewarded/Interstitial Ads
Source: https://docs.adsgram.ai/publisher/reward-interstitial-code-examples
A custom React hook `useAdsgram` to initialize and display ads. It handles ad loading, showing, and callbacks for rewards or errors. This hook is compatible with both Rewarded and Interstitial ad formats.
```javascript
import { useCallback, useEffect, useRef } from 'react';
export function useAdsgram({ blockId, onReward, onError }) {
const AdControllerRef = useRef(undefined);
useEffect(() => {
AdControllerRef.current = window.Adsgram?.init({ blockId });
}, [blockId]);
return useCallback(async () => {
if (AdControllerRef.current) {
AdControllerRef.current
.show()
.then(() => {
// user watch ad till the end or close it in interstitial format
onReward();
})
.catch((result) => {
// user get error during playing ad
onError?.(result);
});
} else {
onError?.({
error: true,
done: false,
state: 'load',
description: 'Adsgram script not loaded',
});
}
}, [onError, onReward]);
}
```
```typescript
import { useCallback, useEffect, useRef } from 'react';
/**
* Check Typescript section
* and use your path to adsgram types
*/
import type { AdController, ShowPromiseResult } from 'path-to-adsgram-types';
export interface useAdsgramParams {
blockId: string;
onReward?: () => void;
onError?: (result: ShowPromiseResult) => void;
}
export function useAdsgram({ blockId, onReward, onError }: useAdsgramParams): () => Promise {
const AdControllerRef = useRef(undefined);
useEffect(() => {
AdControllerRef.current = window.Adsgram?.init({ blockId, debug: true, debugBannerType: 'FullscreenMedia' });
}, [blockId]);
return useCallback(async () => {
if (AdControllerRef.current) {
AdControllerRef.current
.show()
.then(() => {
// user watch ad till the end or close it in interstitial format
onReward?.();
})
.catch((result: ShowPromiseResult) => {
// user get error during playing ad
onError?.(result);
});
} else {
onError?.({
error: true,
done: false,
state: 'load',
description: 'Adsgram script not loaded',
});
}
}, [onError, onReward]);
}
```
--------------------------------
### AdsGram Task Integration
Source: https://docs.adsgram.ai/publisher/task-integration-example
This section details the steps required to integrate the AdsGram task feature into your project. It covers creating a 'Task' type block ID, installing the AdsGram SDK (via script tag or npm), using the `` web component, customizing its appearance with slots and CSS variables, and subscribing to relevant events.
```APIDOC
## AdsGram Task Integration
### Requirements
* A Telegram mini app.
* Understanding of where to display ads (refer to Ad integration examples if needed).
### 1. Create `blockId`
Create a `blockId` with the Block type set to **`Task`**. For detailed instructions, refer to the [Get blockId section].
**WARNING**: Creating more than one Block of type **`Task`** is not allowed for proper functionality.
### 2. Installation
Choose one of the following options to integrate the AdsGram SDK:
#### Option A: Insert Script
Place the `sad.min.js` script in the `` tag of your HTML file:
```html
```
#### Option B: Install via npm (for React and Vue)
* **For React:**
```bash
npm install @adsgram/react
```
* **For Vue:**
```bash
npm install @adsgram/vue
```
Refer to the documentation for React and Vue for more information on task integration using these packages.
### 3. Use `` Web Component
Integrate the task using the `` web component. This component can be used in HTML, React, Vue, and other frameworks as a native HTML element.
```html
```
* `your-block-id`: Obtain this from your AdsGram partner account at `https://partner.adsgram.ai`.
**WARNING**: The `your-block-id` for task ads must be in the format `'task-xxx'`, where **xxx** are numbers.
* **`` Attributes:**
* `data-block-id` (string): Your block ID from `https://partner.adsgram.ai`.
* `data-debug` (boolean): Set to `true` to receive test tasks from the server. Defaults to `false`.
* `data-debug-console` (boolean): Works only if `data-debug` is `true`. If `true`, detailed logs with the prefix `ADSGRAM DEBUG LOG` will be output to the browser console. If `false`, logs are suppressed even in debug mode. Defaults to `true`.
* `class` or `className` (string): Assign a class name for styling the task.
### 4. Customize Task Appearance
Customize the task to match your application's design using slot elements and CSS variables.
#### Slots Usage
The web component supports the following slots, which can be styled using classes:
* `reward`: Displays the reward for completing the task.
* `button`: The button to complete the task.
* `claim`: Displayed instead of the button after the task is completed.
* `done`: Displayed instead of the button after the reward is received.
#### CSS Parameters for Customization
Style the component using the following CSS variables:
```css
--adsgram-task-font-size: /* Font size of the title */
--adsgram-task-icon-size: /* Icon size */
--adsgram-task-icon-title-gap: /* Gap between the icon and the title */
--adsgram-task-icon-border-radius: /* Border radius of the icon */
--adsgram-task-button-width: /* Width of the button for completing the task */
```
### 5. Subscribe to Events
Listen to custom events dispatched by `` using `addEventListener`, similar to standard HTML elements.
#### Event Types
* `reward`: Occurs when a user completes the task.
* `onError`: Occurs when the user encounters an error during task loading or rendering.
* `onBannerNotFound`: Occurs when there are no tasks available to display.
* `onTooLongSession`: Occurs when the user's session is too long, requiring them to restart the app to get ads.
### More Info
* Refer to [code examples] for practical implementation guidance.
* Consult the [Troubleshooting section] if you encounter integration issues.
* Check the [Typescript section] if you are using TypeScript.
```
--------------------------------
### Kochava Tracker Creation and Integration Configuration
Source: https://docs.adsgram.ai/advertiser/tracking
Steps to create an application tracker in Kochava, set up AdsGram as a partner, and configure server-to-server postbacks.
```APIDOC
## Kochava Tracker Creation and Integration Configuration
### Description
This section outlines the procedure for establishing an app tracker within Kochava, integrating AdsGram as a partner, and configuring server-to-server postbacks to relay conversion events.
### Method
POST (for app creation), PUT/POST (for partner integration and postback configuration)
### Endpoint
`/apps` (example for app creation)
`/partners` (example for partner integration)
`/postbacks` (example for postback configuration)
### Parameters
#### Path Parameters
- **app_id** (string) - Required - The unique identifier for the Kochava app tracker.
#### Query Parameters
- **token** (string) - Required - Your unique AdsGram API token.
- **record_data** (string) - Required - Placeholder for conversion data to be sent to AdsGram.
#### Request Body
*For App Creation:*
- **platform** (string) - Required - Application platform (iOS, Android, Web).
- **app_name** (string) - Required - Your app's name.
- **store_id** (string) - Required - App's store identifier.
*For Partner Integration:*
- **partner_name** (string) - Required - Set to 'AdsGram'.
- **tracking_type** (string) - Required - Tracking type (Click-Through, View-Through, Hybrid).
- **server_to_server_postbacks** (boolean) - Required - Set to `true`.
- **postback_url** (string) - Required - The AdsGram endpoint URL: `https://api.adsgram.ai/confirm_conversion`
- **postback_parameters** (object) - Required - Parameters for the postback.
- **record_data** (string) - Required - Placeholder for conversion data.
- **token** (string) - Required - Your unique AdsGram API token.
- **data_mapping** (object) - Required - Mapping of Kochava macros to AdsGram parameters.
- **campaign_id** (string) - Maps Kochava `{campaign_id}`.
- **click_id** (string) - Maps Kochava `{click_id}`.
- **publisher_id** (string) - Maps Kochava `{publisher_id}`.
### Request Example
*App Creation:*
```json
{
"platform": "Android",
"app_name": "My Awesome App",
"store_id": "com.example.myapp"
}
```
*Partner Integration and Postback Configuration:*
```json
{
"partner_name": "AdsGram",
"tracking_type": "Click-Through",
"server_to_server_postbacks": true,
"postback_url": "https://api.adsgram.ai/confirm_conversion",
"postback_parameters": {
"record_data": "{record_data}",
"token": "YOUR_UNIQUE_TOKEN"
},
"data_mapping": {
"campaign_id": "{campaign_id}",
"click_id": "{click_id}",
"publisher_id": "{publisher_id}"
}
}
```
### Response
#### Success Response (200)
*App Creation:*
```json
{
"app_id": "app_xyz",
"status": "created"
}
```
*Partner Integration and Postback Configuration:*
```json
{
"status": "integration_configured",
"postback_url": "https://api.adsgram.ai/confirm_conversion?record={record_data}&token=YOUR_UNIQUE_TOKEN"
}
```
#### Error Response (400/404/500)
```json
{
"error": "Invalid request or server error."
}
```
```
--------------------------------
### Keitaro Tracker Creation and Postback Configuration
Source: https://docs.adsgram.ai/advertiser/tracking
Instructions for creating a tracker in Keitaro and configuring postbacks to send conversion data to AdsGram.
```APIDOC
## Keitaro Tracker Creation and Postback Configuration
### Description
This section details the process of setting up a tracker within the Keitaro platform and configuring postbacks to enable data transfer to AdsGram for conversion tracking.
### Method
POST (for tracker creation), PUT/POST (for postback configuration)
### Endpoint
`/trackers` (example for tracker creation)
`/trackers/{tracker_id}/postback` (example for postback configuration)
### Parameters
#### Path Parameters
- **tracker_id** (string) - Required - The unique identifier for the Keitaro tracker.
#### Query Parameters
- **token** (string) - Required - Your unique AdsGram API token.
- **record** (string) - Required - Placeholder for conversion data to be sent to AdsGram.
#### Request Body
*For Tracker Creation:*
- **name** (string) - Required - The name of the tracker.
- **source_type** (string) - Required - Set to 'AdsGram'.
*For Postback Configuration:*
- **postback_url** (string) - Required - The AdsGram endpoint URL: `https://api.adsgram.ai/confirm_conversion`
- **parameters** (object) - Required - Query parameters for the postback URL.
- **token** (string) - Required - Your unique AdsGram API token.
- **record** (string) - Required - Placeholder for conversion data.
### Request Example
*Tracker Creation:*
```json
{
"name": "My AdsGram Tracker",
"source_type": "AdsGram"
}
```
*Postback Configuration:*
```json
{
"postback_url": "https://api.adsgram.ai/confirm_conversion",
"parameters": {
"token": "YOUR_UNIQUE_TOKEN",
"record": "{record_data}"
}
}
```
### Response
#### Success Response (200)
*Tracker Creation:*
```json
{
"tracker_id": "tracker_123",
"name": "My AdsGram Tracker",
"status": "created"
}
```
*Postback Configuration:*
```json
{
"status": "postback_configured",
"postback_url": "https://api.adsgram.ai/confirm_conversion?token=YOUR_UNIQUE_TOKEN&record={record_data}"
}
```
#### Error Response (400/404/500)
```json
{
"error": "Invalid request or server error."
}
```
```
--------------------------------
### Handle Ad Show Promise and Await
Source: https://docs.adsgram.ai/publisher/api-reference
Demonstrates how to handle the Promise returned by `AdController.show()` using both `.then().catch()` and `async/await` syntax. This allows for rewarding users or handling errors when an ad completes or fails.
```javascript
AdController.show().then((result) => {
// user watch ad till the end
// your code to reward user
}).catch((result) => {
// user get error during playing ad or skip ad
// do nothing or whatever you want
})
```
```javascript
try {
const showPromiseResult = await AdController.show();
// user watch ad till the end
// your code to reward user
} catch (showPromiseResult) {
// user get error during playing ad or skip ad
// do nothing or whatever you want
}
```
--------------------------------
### Kochava Integration Parameters
Source: https://docs.adsgram.ai/advertiser/tracking
Set up server-to-server postbacks in Kochava for AdsGram integration. This includes specifying the AdsGram endpoint, required parameters, and data mapping.
```text
https://api.adsgram.ai/confirm_conversion
{record_data}
token=YOUR_UNIQUE_TOKEN
```
--------------------------------
### Handle Ad Show Promise and Await (TypeScript)
Source: https://docs.adsgram.ai/publisher/api-reference
Demonstrates how to handle the Promise returned by `AdController.show()` in TypeScript using both `.then().catch()` and `async/await` syntax, including type definitions for the `ShowPromiseResult`. This allows for rewarding users or handling errors when an ad completes or fails.
```typescript
const showPromise: Promise = AdController.show();
```
```typescript
AdController.show().then((result: ShowPromiseResult) => {
// user watch ad till the end
// your code to reward user
}).catch((result: ShowPromiseResult) => {
// user get error during playing ad or skip ad
// do nothing or whatever you want
})
```
```typescript
try {
const showPromiseResult: ShowPromiseResult = await AdController.show();
// user watch ad till the end
// your code to reward user
} catch (showPromiseResult: ShowPromiseResult) {
// user get error during playing ad or skip ad
// do nothing or whatever you want
}
```
--------------------------------
### Vanilla JS: AdsGram Task Element Event Handling
Source: https://docs.adsgram.ai/publisher/task-code-examples
This snippet shows how to use the AdsGram task custom element in vanilla JavaScript. It demonstrates attaching event listeners for 'reward', 'onError', 'onBannerNotFound', and 'onTooLongSession' events. The element requires a 'data-block-id' attribute.
```html
🪙 100
go
claim
done
```
```css
.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;
display: block;
width: 328px;
padding: 8px 16px 8px 8px;
border-radius: 16px;
background-color: #1d2733;
font-family: Roboto;
color: white;
}
.task__reward {
margin: 5px 0 0 0;
font-size: 14px;
}
.task__button {
margin-left: 10px;
background-color: #50a8eb;
border-radius: 5px;
padding: 6px 12px;
}
.task__button_claim {
margin-left: 0;
background-color: #ee941c;
}
.task__button_done {
margin-left: 0;
background-color: #007539;
}
```
```javascript
const task = document.querySelector(".task");
task.addEventListener("reward", (event) => {
// event.detail contains your block id
alert(`Reward in block ${event.detail}`);
});
task.addEventListener("onError", (event) => {
alert(`Error during loading or render for block ${event.detail}`);
});
task.addEventListener("onBannerNotFound", (event) => {
alert(`Can't found banner for block ${event.detail}`);
});
task.addEventListener("onTooLongSession", (event) => {
alert('The session is too long. Please restart the app to get ads');
});
```
--------------------------------
### Kochava Campaign Click URL with Macros
Source: https://docs.adsgram.ai/advertiser/tracking
Create a tracking link in Kochava for AdsGram campaigns, incorporating mandatory AdsGram macros for accurate campaign attribution. The {record_data} macro is essential.
```text
https://your-app.kochava.com/install?data={encrypted_data}&campaign_id={campaign_id}&click_id={click_id}&publisher_id={publisher_id}&record={record_data}
```
--------------------------------
### React: AdsGram Task Component (JSX)
Source: https://docs.adsgram.ai/publisher/task-code-examples
This React component, written in JSX, integrates the AdsGram task custom element. It uses `useRef` and `useEffect` to attach and detach event listeners for the 'reward' event. The component conditionally renders based on the availability of the 'adsgram-task' custom element.
```jsx
import { useEffect, useRef } from "react";
import styles from "./task.module.css";
export const Task = ({ debug, blockId }) => {
const taskRef = useRef(null);
useEffect(() => {
const handler = (event) => {
// event.detail contains your block id
alert(`reward, detail = ${event.detail}`);
};
const task = taskRef.current;
if (task) {
task.addEventListener("reward", handler);
}
return () => {
if (task) {
task.removeEventListener("reward", handler);
}
};
}, []);
if (!customElements.get("adsgram-task")) {
return null;
}
return (
1000 coins
go
claim
done
);
};
```
--------------------------------
### AdController methods - show
Source: https://docs.adsgram.ai/publisher/api-reference
Loads and displays an ad. Returns a Promise that resolves if the user watches the ad completely, or rejects otherwise.
```APIDOC
## POST /websites/adsgram_ai/AdController/show
### Description
Loads and shows an ad. This method returns a Promise that resolves when the user has watched the ad until the end, or rejects if there's an error during playback or if the user skips the ad.
### Method
POST
### Endpoint
/websites/adsgram_ai/AdController/show
### Parameters
None
### Request Example
```javascript
AdController.show();
```
### Response
#### Success Response (200)
- **Promise** (Promise) - A promise that resolves with a `ShowPromiseResult` object upon successful ad completion.
```typescript
interface ShowPromiseResult {
done: boolean; // true if user watched till the end, otherwise false
description: string; // event description
state: 'load' | 'render' | 'playing' | 'destroy'; // banner state
error: boolean; // true if event was emitted due to error, otherwise false
}
```
#### Response Example
```javascript
AdController.show().then((result) => {
// user watched ad till the end
// your code to reward user
}).catch((result) => {
// user encountered an error during ad playback or skipped the ad
// handle accordingly
});
```
```
--------------------------------
### React: AdsGram Task Component (TSX)
Source: https://docs.adsgram.ai/publisher/task-code-examples
This React component, written in TSX, provides TypeScript support for integrating the AdsGram task custom element. It includes type definitions for props and uses `useRef` with a generic type for the custom element. Event listeners are managed within `useEffect` for the 'reward' event.
```tsx
import { useEffect, useRef } from "react";
import styles from "./task.module.css";
import { JSX } from "react/jsx-runtime";
/**
* Check Typescript section
* and add types for typing
*/
interface TaskProps {
debug: boolean;
blockId: string;
}
export const Task = ({ debug, blockId }: TaskProps) => {
const taskRef = useRef(null);
useEffect(() => {
const handler = (event: CustomEvent) => {
// event.detail contains your block id
alert(`reward, detail = ${event.detail}`);
};
const task = taskRef.current;
if (task) {
task.addEventListener("reward", handler);
}
return () => {
if (task) {
task.removeEventListener("reward", handler);
}
};
}, []);
if (!customElements.get("adsgram-task")) {
return null;
}
return (
1000 coins
go
claim
done
);
};
```
--------------------------------
### Initialize AdsGram SDK
Source: https://docs.adsgram.ai/publisher/reward-interstitial-integration
How to initialize the AdsGram SDK with your blockId. This is required for Rewarded and Interstitial formats.
```APIDOC
## Initialize AdsGram SDK
### Description
Initializes the AdsGram SDK. This step is mandatory for Rewarded and Interstitial ad formats. For the 'Task' format, initialization is not required.
### Method
JavaScript
### Endpoint
```javascript
const AdController = window.Adsgram.init({ blockId: "your-block-id" });
```
### Parameters
#### Request Body
- **blockId** (string) - Required - The unique identifier for your ad block, obtained from your AdsGram partner account.
```
--------------------------------
### Keitaro Postback Configuration
Source: https://docs.adsgram.ai/advertiser/tracking
Configure the postback URL in Keitaro to send conversion data to AdsGram. This involves specifying the AdsGram endpoint and required query parameters.
```text
https://api.adsgram.ai/confirm_conversion
token=YOUR_UNIQUE_TOKEN&record={record_data}
```
--------------------------------
### Adsgram methods - init
Source: https://docs.adsgram.ai/publisher/api-reference
Initializes the AdController for a given blockId. This function should be called once per blockId. Subsequent calls with the same blockId will return the same AdController instance.
```APIDOC
## POST /websites/adsgram_ai/init
### Description
Creates an `AdController` instance used for showing, loading, and destroying ads. It's recommended to initialize only once per `blockId`. If `init` is called multiple times with the same `blockId`, the same `AdController` will be returned.
### Method
POST
### Endpoint
/websites/adsgram_ai/init
### Parameters
#### Request Body
- **blockId** (string) - Required - The unique identifier of the ad block.
- **debug** (boolean) - Optional - Enables test ads and detailed logs for integration debugging. Set to `false` for production.
- **debugConsole** (boolean) - Optional - If `true` (and `debug` is `true`), detailed logs are output to the browser console. Defaults to `true`.
- **debugBannerType** (string) - Optional - Specifies the test banner type (`"FullscreenMedia"` or `"RewardedVideo"`). Works only if `debug` is `true`.
### Request Example
```json
{
"blockId": "your-block-id",
"debug": true,
"debugConsole": true,
"debugBannerType": "FullscreenMedia"
}
```
### Response
#### Success Response (200)
- **AdController** (object) - An instance of the AdController used to manage ads.
```
--------------------------------
### Initialize AdsGram SDK (JavaScript)
Source: https://docs.adsgram.ai/publisher/reward-interstitial-integration
Initializes the AdsGram SDK with a provided blockId. This step is crucial for Rewarded and Interstitial ad formats. The blockId is obtained from your AdsGram partner account.
```javascript
const AdController = window.Adsgram.init({ blockId: "your-block-id" });
```
--------------------------------
### Keitaro Campaign Click URL with Macros
Source: https://docs.adsgram.ai/advertiser/tracking
Construct the Click URL in Keitaro for AdsGram campaigns, including necessary AdsGram macros for detailed tracking. Ensure the {record_data} macro is present.
```text
https://your-keitaro-domain.com/click.php?campaign_id={campaign_id}&subid={click_id}&publisher={publisher_id}&banner={banner_id}&record={record_data}
```
--------------------------------
### Control Ad Playback with AdController
Source: https://docs.adsgram.ai/publisher/api-reference
Provides methods to control the ad lifecycle. `show()` loads and displays an ad, returning a Promise that resolves on successful completion or rejects on error/skip. `destroy()` stops the ad and cleans up loaded data. Event listeners can be added for more granular control.
```javascript
AdController.show();
```
```javascript
AdController.destroy();
```
```javascript
AdController.addEventListener('onReward', () => {
// your code to reward user
});
```