K2 AdServing SDK

K2 is an adserving system developed by DAT, designed to help advertisers seamlessly integrate traditional programmatic advertising with Web3-based reward ad formats, such as offerwalls. Built as a SAAS platform, K2 enables efficient ad matching and delivery across diverse ecosystems.

Features

• 🎯 Programmatic Ad Integration
• 💎 Web3 Reward-Based Formats
• 💰 Offerwall Implementation
• 🔄 Real-time Ad Matching
• 🌐 Cross-ecosystem Support
• 📊 Performance Analytics
• 🔍 Automatic Telegram User ID Detection
• 💰 Reward Balance Tracking
• 🔍 Telegram WebApp Detection

Installation

npm install @dat-platform/k2-adserving
# or
yarn add @dat-platform/k2-adserving

Quick Start

Note: When using within a Telegram Mini App, the SDK automatically detects the user's Telegram ID. You don't need to manually pass user_unique_id unless you're using it outside of Telegram or want to override the automatic detection.

Initialize the SDK

The SDK uses a singleton pattern for efficient resource management:

import K2SDK from '@dat-platform/k2-adserving';

// 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

After initialization, access the SDK instance from anywhere in your application:

// Get the SDK instance
const sdk = K2SDK.getInstance();

// Get Offer Wall
try {
  const offers = await sdk.getOfferWall('YOUR_PLACEMENT_ID', {
    user_unique_id: 'OPTIONAL_USER_ID',
    limit: 10 // Optional , Default is 3
  });
  console.log('Offers:', offers);
} catch (error) {
  console.error('Failed to fetch offers:', error);
}

// Get Ads only single ad will come
try {
  const ads = await sdk.getAd('YOUR_PLACEMENT_ID', {
    user_unique_id: 'OPTIONAL_USER_ID'
  });
  console.log('Ads:', ads);
} catch (error) {
  console.error('Failed to fetch ads:', error);
}

// Get Reward Balance
try {
  const balance = await sdk.getRewardBalance('YOUR_PLACEMENT_ID', {
    user_unique_id: 'OPTIONAL_USER_ID'
  });
  console.log('Reward Balance:', balance.results.reward_balance);
} catch (error) {
  console.error('Failed to fetch reward balance:', error);
}

// Check if running in Telegram WebApp
const isTelegramApp = sdk.isTelegramWebAppAvailable();
console.log('Is Telegram WebApp:', isTelegramApp);

// Get Telegram User ID (Only works in Telegram WebApp)
try {
  const telegramUserId = sdk.getTelegramUserId();
  console.log('Telegram User ID:', telegramUserId);
} catch (error) {
  console.error('Not running in Telegram:', error);
}

React Integration Example

import React, { useEffect, useState } from 'react';
import K2SDK from '@dat-platform/k2-adserving';

const MyComponent = () => {
  const [offers, setOffers] = useState([]);

  useEffect(() => {
    const fetchOffers = async () => {
      try {
        const sdk = K2SDK.getInstance();
        const offerWall = await sdk.getOfferWall("YOUR_PLACEMENT_ID");
        setOffers(offerWall);
      } catch (error) {
        console.error('Failed to fetch offers:', error);
      }
    };

    fetchOffers();
  }, []);

  return (
    // Your component JSX
  );
};

Sample OfferWall JSON Example

[
{
    "url": "https://cms.datplatform.com/click?url=https%3A%2F%2Fr.datplatform.com%2Fadx-dir-d%2Fctrk%2Ffc4742ede628bf396a7032d4df5cfb117fc8fb3fbb2ed7c02cf67f2b8d279a9c%2F%5BADX_TXN_ID%5D%2F%5BAUCTION_PRICE%5D%2F%5Bexternalid%5D&id=f44d742efeb895f8a2e103370cb361a4794592e8893cb4668de75a82da3457b3a241ba88062506f3031e8ba2c785f3627b38cb5016dc1d8b2bdf6ddf4b8c417c",
    "icon": "https://cdn.datplatform.com/7_310024_0.png",
    "title": "subway surfers !",
    "reward": "50",
    "offerId": 310024,
    "currency": "USD",
    "campaignId": 410003,
    "description": "Reach level 19 and earn multiple rewads playing subway trek !",
    "adtype_action": "click_reward",
    "impressionTrackURL": "https://cms.datplatform.com/imps?url=https%3A%2F%2Fr.datplatform.com%2Fadx-dir-d%2Fctrk%2Ffc4742ede628bf396a7032d4df5cfb117fc8fb3fbb2ed7c02cf67f2b8d279a9c%2F%5BADX_TXN_ID%5D%2F%5BAUCTION_PRICE%5D%2F%5Bexternalid%5D"
}
]

Custom Targeting Fields

When fetching offers or ads, you can utilize custom fields for more precise targeting. The K2 AdServing SDK supports the following targeting parameters:

| Field Name | Field Key | Description | |------------|-----------|-------------| | Wallet ID | wid | Digital wallet ID used by the user when registering on the publisher side | | User Group | ug | User groups defined by the publisher for users | | Social Handles | sh | Social platforms associated with the users registration | | Phone Number Hash Type | pnht | Phone number encryption method | | Phone Number | pn | Users phone number | | Email Hash Type | emht | Email encryption method | | Email | em | Users email address | | Country | ct | Country specified by the user during registration | | Blockchain | bc | This field can quickly identify which blockchain a particular wallet ID is transacting or storing assets on | | Account Creation Date | acd | Date when the user registered |

Example Usage

// Get Offer Wall with custom targeting fields
try {
  const offers = await sdk.getOfferWall('YOUR_PLACEMENT_ID', {
    user_unique_id: 'OPTIONAL_USER_ID',
    limit: 10, // Optional, Default is 3
    
    // Custom targeting fields (use the field keys shown in the table above)
    wid: '0x1234567890abcdef', 
    ug: 'premium',
    sh: 'telegram',
    pnht: 'sha256',
    pn: '+1234567890',
    emht: 'md5',
    em: '[email protected]',
    ct: 'US',
    bc: 'ethereum',
    acd: '2023-04-15'
  });
  console.log('Targeted Offers:', offers);
} catch (error) {
  console.error('Failed to fetch targeted offers:', error);
}

These custom targeting parameters help deliver more relevant offers to your users, improving conversion rates and user experience. You can include any combination of the parameters listed above that are relevant to your application.

Error Handling

The SDK implements comprehensive error handling:

• Initialization errors
• API request failures
• Invalid parameter validation
• Network connectivity issues

Always use try-catch blocks when implementing SDK methods.

Support

For technical support or inquiries:

• Email: [email protected]
• Website: https://www.dat.network

About DAT

DAT is a collaborative team from China and India, focused on developing innovative solutions that bridge traditional programmatic advertising with Web3 technologies. K2 is our flagship adserving platform, designed to empower advertisers with next-generation ad delivery capabilities.

License

This project is licensed under the MIT License - see the LICENSE file for details.