Adrop Ads Web SDK

Official Web SDK for Adrop advertising platform. Integrate direct deal ads seamlessly into your web applications.

Features

• 🚀 Easy integration with both npm and CDN
• 📱 Banner and Native ad formats
• 🎯 Direct deal advertising
• 🔒 Secure iframe-based ad rendering
• 📊 Built-in event tracking
• 🎨 Customizable native ad rendering
• ⚡ Lightweight and performant
• 🔧 TypeScript support

Installation

NPM

npm install @adrop/ads-web-sdk

CDN

<script src="https://cdn.jsdelivr.net/npm/@adrop/ads-web-sdk@latest/dist/adrop-ads.min.js"></script>

Quick Start

1. Initialize the SDK

import Adrop from '@adrop/ads-web-sdk';

const adrop = Adrop.observe({
  uid: 'your-user-id',
  appId: 'your-app-id',
  debug: true // Set to false in production
});

For CDN usage:

<script>
  const adrop = Adrop.observe({
    uid: 'your-user-id',
    appId: 'your-app-id',
    debug: true
  });
</script>

2. Load Banner Ads

Automatic Loading (Declarative)

<div data-adrop-unit="YOUR_UNIT_ID"></div>

The SDK automatically detects and loads ads in elements with data-adrop-unit attribute.

Optional data attributes:

• data-adrop-context-id: Context ID for contextual targeting
• data-adrop-theme: Theme for light/dark mode (values: light, dark)

<div
  data-adrop-unit="YOUR_UNIT_ID"
  data-adrop-context-id="CONTEXT_ID"
  data-adrop-theme="dark">
</div>

Programmatic Loading

const container = document.getElementById('ad-container');

await adrop.renderAd(container, {
  unit: 'YOUR_UNIT_ID'
});

The SDK automatically detects and renders native ads.

Optional field:

• contextId: Context ID for contextual targeting
• theme: Theme for light/dark mode (values: light, dark)

const container = document.getElementById('ad-container');

await adrop.renderAd(container, {
    unit: 'YOUR_UNIT_ID',
    contextId: 'CONTEXT_ID',
    theme: 'dark'
});

3. Load Native Ads

Native ads provide customizable ad experiences that blend seamlessly with your app's content. They require custom UI implementation using the data-adrop-native attributes.

Automatic Loading with Custom UI (Declarative)

To use custom UI, you must set data-adrop-render="custom":

<div data-adrop-unit="YOUR_NATIVE_UNIT_ID" data-adrop-render="custom">
  <!-- Native ad components with data-adrop-native attributes -->
  <div class="ad-profile">
    <img data-adrop-native="profile.displayLogo" class="ad-profile-logo" alt="Profile">
    <span data-adrop-native="profile.displayName" class="ad-profile-name"></span>
  </div>
  <h3 data-adrop-native="headline" class="ad-headline"></h3>
  <img data-adrop-native="asset" class="ad-image" alt="Ad Image">
  <p data-adrop-native="body" class="ad-description"></p>
  <button data-adrop-native="callToAction" class="ad-cta-button"></button>
</div>

For entire area click functionality:

<div 
  data-adrop-unit="YOUR_NATIVE_UNIT_ID" 
  data-adrop-render="custom"
  data-adrop-entire-click="true">
  <!-- Entire container becomes clickable -->
  <div class="ad-profile">
    <img data-adrop-native="profile.displayLogo" class="ad-profile-logo" alt="Profile">
    <span data-adrop-native="profile.displayName" class="ad-profile-name"></span>
  </div>
  <h3 data-adrop-native="headline" class="ad-headline"></h3>
  <img data-adrop-native="asset" class="ad-image" alt="Ad Image">
  <p data-adrop-native="body" class="ad-description"></p>
  <span data-adrop-native="callToAction" class="ad-cta-text"></span>
</div>

Programmatic Loading with Custom UI

const container = document.getElementById('native-ad-container');

await adrop.renderAd(container, {
  unit: 'YOUR_NATIVE_UNIT_ID',
  trackMode: 1 // Required for custom UI
});

For entire area click functionality:

const container = document.getElementById('native-ad-container');

await adrop.renderAd(container, {
  unit: 'YOUR_NATIVE_UNIT_ID',
  trackMode: 1, // Required for custom UI
  isEntireClick: true // Makes entire container clickable
});

Available data-adrop-native Fields

The SDK supports the following data-adrop-native attributes:

Basic Fields:

• headline: Ad headline text
• body: Ad description text
• callToAction: Call-to-action button text
• asset: Main ad image URL

Profile Fields (for advertiser information):

• profile.displayLogo: Advertiser logo image URL
• profile.displayName: Advertiser name text

Extra Fields (custom properties):

• extra.{key}: Custom field from ad data (e.g., extra.price, extra.rating)

Custom UI Implementation Example

<div data-adrop-unit="YOUR_NATIVE_UNIT_ID" data-adrop-render="custom" class="native-ad-container">
  <!-- Advertiser Profile -->
  <div class="advertiser-info">
    <img data-adrop-native="profile.displayLogo" class="advertiser-logo" alt="Advertiser">
    <span data-adrop-native="profile.displayName" class="advertiser-name"></span>
  </div>
  
  <!-- Ad Content -->
  <div class="ad-content">
    <h2 data-adrop-native="headline" class="ad-title"></h2>
    <img data-adrop-native="asset" class="ad-main-image" alt="Ad">
    <p data-adrop-native="body" class="ad-text"></p>
    
    <!-- Custom Fields -->
    <div class="ad-extras">
      <span data-adrop-native="extra.price" class="price-tag"></span>
      <span data-adrop-native="extra.rating" class="rating"></span>
    </div>
    
    <button data-adrop-native="callToAction" class="cta-button"></button>
  </div>
</div>

Click Behavior Control

You can control how clicks are handled in native ads:

Individual Element Clicks (default):

• Only elements with data-adrop-native attributes are clickable
• Each text and image element handles its own click

Entire Area Clicks:

• Set data-adrop-entire-click="true" (declarative) or isEntireClick: true (programmatic)
• The entire ad container becomes clickable
• Useful for card-style layouts where any part of the ad should be clickable

Important Notes:

• Custom UI requires data-adrop-render="custom" or trackMode: 1
• Click behavior: isEntireClick: true makes entire area clickable, otherwise only individual elements
• The SDK automatically handles click tracking and impression tracking
• Elements with data-adrop-native will be automatically populated with ad content
• Missing fields will be left empty (no error thrown)
• Profile clicks redirect to advertiser pages, other clicks go to ad landing pages

4. Event Handling

Listen to ad lifecycle events:

// Ad received successfully
adrop.on(Adrop.Events.AD_RECEIVED, (unit, adData) => {
  console.log('Ad received:', unit, adData);
});

// Ad failed to load
adrop.on(Adrop.Events.AD_FAILED, (unit) => {
  console.error('Ad failed:', unit);
});

// No ad available
adrop.on(Adrop.Events.AD_NO_FILL, (unit) => {
  console.warn('No ad available:', unit);
});

// No backfill ad available
adrop.on(Adrop.Events.AD_BACKFILL_NO_FILL, (unit) => {
  console.warn('No backfill ad available:', unit);
});

// Ad impression
adrop.on(Adrop.Events.AD_IMPRESSION, (unit, adData) => {
  console.log('Ad impression:', unit, adData);
});

// Ad clicked
adrop.on(Adrop.Events.AD_CLICKED, (unit, adData) => {
  console.log('Ad clicked:', unit, adData);
});

Advanced Usage

Update Properties

Properties can be chained and committed together in a single call:

// Set app key
adrop.appKey = 'YOUR_APP_KEY';

// Chain multiple property updates and commit once
await adrop.metrics
  .setUserProperties({
    last_login: new Date().toISOString(),
    age: '25',
    gender: 'M',
    // Custom properties can be added directly
    theme: 'dark',
    language: 'en'
  })
  .setAppProperties({
    version: '1.0.0',
    platform: 'web'
  })
  .commit();

Context Targeting

Use contextId to enable contextual targeting for more relevant ads:

await adrop.renderAd(container, {
  unit: 'YOUR_UNIT_ID',
  contextId: 'YOUR_CONTEXT_ID' // Context ID from Adrop Console
});

The contextId should match the ID configured in your Adrop Console under Targeting Menu > Context Targeting.

Theme Support

The SDK supports light and dark themes for ads. You can set the theme using the data-adrop-theme attribute or the theme option in renderAd.

Load Backfill Ads

Backfill ads are automatically loaded when direct deal ads are not available.

Note: Backfill configuration must be set up in the Adrop Console for this to work.

Clear Ads

Remove ads from containers:

const container = document.getElementById('ad-container');
adrop.clear(container);

Reload Ads

In HTML, you can reload ads by calling:

const container = document.getElementById('ad-container');
const paramsToOverride = {
    unit: 'NEW_UNIT_ID',
    contextId: 'NEW_CONTEXT_ID',
    theme: 'light'
}
adrop.renderAd(container, paramsToOverride);

// if you don't want to override previous params, just call without second argument
adrop.renderAd(container);

Update User ID

adrop.uid = 'new-user-id';

Configuration Options

Initialization Options

{
  uid?: string;           // User identifier
  appId?: string;         // Application ID
  appKey?: string;        // Application key
  debug?: boolean;        // Enable debug logging (default: false)
}

Ad Request Options

{
  unit: string;           // Ad unit ID (required)
  uid?: string;           // Override user ID for this request
  contextId?: string;     // Context identifier
  trackMode?: number;     // Tracking mode
}

Events

• AD_RECEIVED - Ad successfully loaded
• AD_FAILED - Ad failed to load
• AD_NO_FILL - No ad available for this request
• AD_BACKFILL_NO_FILL - No backfill ad available
• AD_IMPRESSION - Ad impression recorded
• AD_CLICKED - User clicked on the ad

TypeScript Support

The SDK includes TypeScript definitions out of the box:

import Adrop, { AdropConfig, AdData } from '@adrop/ads-web-sdk';

const config: AdropConfig = {
  uid: 'user-123',
  debug: true
};

const adrop = Adrop.observe(config);

SPA Support

For Single Page Applications, clear previous ads when navigating:

function navigateToNewPage() {
  // Clear existing ads
  const adElements = document.querySelectorAll('[data-adrop-unit]');
  adElements.forEach(element => adrop.clear(element));

  // Load new page content
  loadNewPageContent();
}

License

Copyright 2025 Open Rhapsody Co., Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.