@dat-platform/advertiser/readme.md

An SDK for advertisers to track user actions, such as Telegram channel or bot joins, and notify publishers upon completion.

# K2 Advertising SDK

K2 is a powerful advertising solution developed by DAT, designed to seamlessly integrate traditional programmatic advertising with Web3-based rewards. As a SaaS platform, K2 ensures efficient ad matching and delivery across diverse digital ecosystems.

## Key Features

- 🎯 **Programmatic Ad Integration**
- 💎 **Web3 Reward-Based Ad Formats**
- 🌐 **Cross-Ecosystem Compatibility**
- 📊 **Advanced Performance Analytics**
- 🔍 **Automatic Telegram User ID Detection**
- 💰 **Reward Balance Distribution**
- 🔍 **Seamless Telegram WebApp Support**

## Installation

Install the SDK using either `npm` or `yarn`:

```bash
npm install @dat-platform/advertiser
# or
yarn add @dat-platform/advertiser
```

## Getting Started

> **Note**: When using the SDK within a Telegram Mini App, it automatically detects the user's Telegram ID. If using it outside Telegram or overriding detection, you may need to pass `user_unique_id` manually.

### SDK Initialization

The SDK follows a singleton pattern to optimize resource usage:

```javascript
import K2SDK from '@dat-platform/advertiser';

// Initialize the SDK
try {
  const sdk = await K2SDK.initialize({
    apiKey: 'YOUR_API_KEY',
  });
  console.log('K2 SDK initialized successfully');
} catch (error) {
  console.error('SDK initialization failed:', error);
}
```

### Using the SDK

Once initialized, you can access the SDK instance anywhere in your application:

```javascript
// Retrieve SDK instance
const sdk = K2SDK.getInstance();

// Mark an action as complete
try {
  const response = await sdk.markActionComplete('YOUR_ADVERTISER_ID', 'TXN_ID');
  console.log('Response:', response);
} catch (error) {
  console.error('Failed to send rewards:', error);
}
```

### React Integration Example

```javascript
import React, { useEffect, useState } from 'react';
import K2SDK from '@dat-platform/advertiser';

const MyComponent = () => {
  const [taskCompleted, setTaskCompleted] = useState(false);
  const [result, setResult] = useState([]);

  useEffect(() => {
    if(taskCompleted === true ){
      onActionComplete();
    }
  }, [taskCompleted]);

  const onActionComplete = async () => {
    try {
        const sdk = K2SDK.getInstance();
        const response = await sdk.markActionComplete('YOUR_ADVERTISER_ID', 'TXN_ID');
        console.log('Response:', response);
        setResult(response)
      } catch (error) {
        console.error('Failed to send rewards:', error);
      }
  }

  return (
    // Your component JSX
  );
};
```

## Error Handling

K2 SDK provides robust error handling for:
- Initialization failures
- API request errors
- Invalid parameter inputs
- Network issues

Always wrap SDK methods in `try-catch` blocks to manage potential errors effectively.

## Support

For assistance or inquiries:
- 📧 Email: [tony@dat.network](mailto:tony@dat.network)
- 🌍 Website: [https://www.dat.network](https://www.dat.network)

## About DAT

DAT is a dynamic team from China and India, dedicated to innovating the intersection of programmatic advertising and Web3 technologies. K2 is our flagship ad-serving platform, empowering advertisers with next-generation ad delivery solutions.

## License

This project is licensed under the **MIT License**. See the LICENSE file for more details.