@dat-platform/k2-adserving NPM

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: 'user@example.com',
    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: tony@dat.network
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.