AdTrust

Versatile Ad Delivery Library

AdTrust is a lightweight yet powerful JavaScript library for ad delivery with comprehensive viewability tracking, multi-format support, and basic ad blocker detection.

Features

• Multiple Ad Formats: Support for banner, HTML, third-party tag, and video ads
• IAB/MRC Compliant Viewability Tracking: Follows industry standards for viewable impressions
• Lazy Loading: Efficient resource management with configurable thresholds
• Auto-Refresh: Optional timed refresh for ads when they're in view
• Ad Blocker Detection: Basic detection with customizable callbacks
• Detailed Event Tracking: Comprehensive events for viewability metrics
• Flexible Integration: Both declarative (HTML) and programmatic (JS) implementations

IAB/MRC Compliance

AdTrust implements IAB (Interactive Advertising Bureau) and MRC (Media Rating Council) viewability standards:

• Display ads are considered viewable when 50% of pixels are in view for at least 1 second
• Large display ads (>242,500 pixels) use 30% viewability threshold per IAB guidelines
• Video ads require 50% of pixels in view for at least 2 seconds
• Detailed quartile tracking (25%, 50%, 75%, 100%) for both viewability and video progress
• Proper viewability measurement using IntersectionObserver API

Installation

Via CDN (recommended)

<script src="https://unpkg.com/adtrust"></script>

Via NPM

npm install adtrust

Then import in your project:

import AdTrust from 'adtrust';
// or
const AdTrust = require('adtrust');

Usage

AdTrust supports both declarative (HTML) and programmatic (JavaScript) implementations.

Declarative Implementation (HTML)

Add script tags with data attributes to define ads:

<!-- Banner Ad -->
<script
  data-type="banner"
  data-image-url="https://example.com/ad.jpg"
  data-click-url="https://example.com"
  data-width="300"
  data-height="250">
</script>

<!-- HTML Ad -->
<script
  data-type="html"
  data-html-content="<div>My custom HTML ad</div>"
  data-width="300"
  data-height="250">
</script>

<!-- Third-Party Tag Ad -->
<script
  data-type="tag"
  data-tag-url="https://adserver.example.com/tag.html"
  data-width="300"
  data-height="250">
</script>

<!-- Video Ad -->
<script
  data-type="video"
  data-video-url="https://example.com/ad.mp4"
  data-poster-url="https://example.com/poster.jpg"
  data-width="640"
  data-height="360"
  data-autoplay="true"
  data-muted="true">
</script>

Programmatic Implementation (JavaScript)

Create ads programmatically:

// Banner Ad
AdTrust.createAd({
  adType: "banner",
  imageUrl: "https://example.com/ad.jpg",
  clickUrl: "https://example.com",
  width: 300,
  height: 250
});

// HTML Ad
AdTrust.createAd({
  adType: "html",
  htmlContent: "<div>My custom HTML ad</div>",
  width: 300,
  height: 250
});

// Third-Party Tag Ad
AdTrust.createAd({
  adType: "tag",
  tagUrl: "https://adserver.example.com/tag.html",
  width: 300,
  height: 250
});

// Video Ad
AdTrust.createAd({
  adType: "video",
  videoUrl: "https://example.com/ad.mp4",
  posterUrl: "https://example.com/poster.jpg",
  width: 640,
  height: 360,
  autoplay: true,
  muted: true
});

Configuration Parameters

Common Parameters (All Ad Types)

Viewability Parameters

Global Configuration

Banner Ad Parameters

HTML Ad Parameters

Third-Party Tag Ad Parameters

Video Ad Parameters

API Reference

Main Methods

// Create any type of ad
const adInstance = AdTrust.createAd(options);

// Initialize ads from script tags in the document
AdTrust.initFromTag();

// Initialize a specific script tag by selector
AdTrust.initSpecificTag('#my-ad-script');

// Get all ad instances
const allAds = AdTrust.getAdInstances();

// Get a specific ad by ID
const myAd = AdTrust.getAdById('my-ad-id');

// Load a delayed ad immediately
AdTrust.loadDelayedAdNow('my-delayed-ad-id');

// Load all delayed ads immediately
AdTrust.loadAllDelayed();

// Get aggregated metrics for all ads
const metrics = AdTrust.getAggregateMetrics();

// Destroy all ad instances
AdTrust.destroyAll();

// Set global configuration
AdTrust.setGlobalConfig({
  viewabilityThreshold: 0.6,
  refreshInterval: 60000,
  enableRefresh: true
});

// Enable/disable debug mode
AdTrust.setDebugMode(true);

Ad Instance Methods

// Load ad content (typically happens automatically)
adInstance.loadContent();

// Refresh the ad
adInstance.refresh();

// Get viewability metrics
const metrics = adInstance.getViewabilityMetrics();

// For video ads, get video-specific metrics
const videoMetrics = adInstance.getVideoMetrics();

// Destroy the ad instance
adInstance.destroy();

Events

AdTrust dispatches custom events on ad elements, which you can listen for:

document.addEventListener('adTrust:viewableImpression', function(e) {
  console.log('Ad viewable:', e.detail);
});

Available events:

Ad Blocker Detection

AdTrust includes basic ad blocker detection using a "bait" method:

// Set custom callback
AdTrust.setGlobalConfig({
  adBlockerDetectedCallback: function() {
    console.log('Ad blocker detected!');
    // Display alternative content or messaging
  }
});

// Check status in metrics
const metrics = AdTrust.getAggregateMetrics();
if (metrics.isAdBlockerSuspected) {
  // Handle ad blocker presence
}

Advanced Usage Examples

Using HTML Templates

<!-- Define template -->
<script id="my-html-ad" type="text/html">
  <div class="custom-ad">
    <h3>Special Offer!</h3>
    <p>Limited time only</p>
    <button>Learn More</button>
  </div>
</script>

<!-- Reference template in ad -->
<script data-type="html" data-html-template-id="my-html-ad"></script>

Global Configuration

// Set global configuration for all ads
AdTrust.setGlobalConfig({
  viewabilityThreshold: 0.7,
  refreshInterval: 60000,
  enableRefresh: true,
  logViewabilityEvents: true,
  reportEndpoint: 'https://analytics.example.com/beacons',
  adBlockerDetectedCallback: function() {
    console.log('Ad blocker detected');
  }
});

Custom Container Placement

<!-- Define a container -->
<div id="ad-container"></div>

<!-- Reference container in ad -->
<script data-type="banner"
  data-container-id="ad-container"
  data-image-url="https://example.com/ad.jpg">
</script>

YouTube Video Support

AdTrust supports YouTube videos in video ads:

AdTrust.createAd({
  adType: "video",
  videoUrl: "https://www.youtube.com/watch?v=VIDEO_ID",
  width: 640,
  height: 360,
  autoplay: true,
  muted: true
});

Browser Compatibility

AdTrust is compatible with all modern browsers:

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 16+
• Opera 47+

Some features may require polyfills for older browsers:

• IntersectionObserver
• Custom Events
• Promises

License

ISC License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.