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)

| Parameter | Data Attribute | Type | Default | Description | |-----------|----------------|------|---------|-------------| | id | data-id | String | Auto-generated | Unique identifier for the ad | | containerId | data-container-id | String | null | ID of container element. If not provided, one will be created | | width | data-width | Number | null | Width of ad in pixels | | height | data-height | Number | null | Height of ad in pixels | | clickUrl | data-click-url | String | null | URL to navigate to when ad is clicked | | delay | data-delay | String/Number | "0" | Delay in ms before loading the ad. Can include units: "2s", "500" | | adType | data-type | String | "banner" | Type of ad: "banner", "html", "tag", "video" |

Viewability Parameters

| Parameter | Data Attribute | Type | Default | Description | |-----------|----------------|------|---------|-------------| | viewabilityThreshold | data-viewability-threshold | Number | 0.5 | Percentage of ad that must be visible (0.0-1.0) | | viewabilityTime | data-viewability-time | Number | 1000 | Time in ms ad must be visible to count as viewable | | heartbeatInterval | data-heartbeat-interval | Number | 250 | Interval in ms for checking viewability | | lazyLoadThreshold | data-lazy-load-threshold | Number | 1 | Screen heights away from viewport to trigger lazy loading | | refreshInterval | data-refresh-interval | Number | 30000 | Time in ms between ad refreshes if enabled | | enableRefresh | data-enable-refresh | Boolean | false | Whether to automatically refresh the ad | | logViewabilityEvents | data-log-viewability | Boolean | false | Whether to log viewability events to console | | reportEndpoint | data-report-endpoint | String | null | URL to send viewability beacons to |

Global Configuration

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | logErrors | Boolean | true | Log errors to console | | detectAdBlocker | Boolean | true | Detect ad blockers on initialization | | adBlockerDetectedCallback | Function | null | Function to call if ad blocker is detected | | onErrorCallback | Function | null | Function to call on errors | | debug | Boolean | false | Enable debug mode with verbose logging | | autoInit | Boolean | true | Automatically initialize ads from script tags |

Banner Ad Parameters

| Parameter | Data Attribute | Type | Required | Description | |-----------|----------------|------|----------|-------------| | imageUrl | data-image-url | String | Yes | URL of the image to display | | imageObjectFit | data-image-object-fit | String | No | CSS object-fit property for the image (cover, contain, etc.) | | imageAltText | data-image-alt-text | String | No | Alt text for the image for accessibility |

HTML Ad Parameters

| Parameter | Data Attribute | Type | Required | Description | |-----------|----------------|------|----------|-------------| | htmlContent | data-html-content | String | Yes* | HTML content to display (or use template) | | htmlTemplateId | data-html-template-id | String | Yes | ID of script tag containing HTML template (*or use content) | | useSandbox | data-use-sandbox | Boolean | No (true) | Whether to use iframe sandbox for security |

Third-Party Tag Ad Parameters

| Parameter | Data Attribute | Type | Required | Description | |-----------|----------------|------|----------|-------------| | tagUrl | data-tag-url | String | Yes | URL of the third-party ad tag | | useSandbox | data-use-sandbox | Boolean | No (true) | Whether to use iframe sandbox for security |

Video Ad Parameters

| Parameter | Data Attribute | Type | Required | Description | |-----------|----------------|------|----------|-------------| | videoUrl | data-video-url | String | Yes | URL of the video to play | | posterUrl | data-poster-url | String | No | URL of the poster image to show before play | | autoplay | data-autoplay | Boolean | No (false) | Whether to autoplay the video | | controls | data-controls | Boolean | No (true) | Whether to show video controls | | muted | data-muted | Boolean | No (true) | Whether to mute the video | | loop | data-loop | Boolean | No (false) | Whether to loop the video |

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:

| Event | Description | |-------|-------------| | adTrust:loaded | Ad content has loaded | | adTrust:loadError | Error loading ad content | | adTrust:delayComplete | Delay timer completed | | adTrust:viewableStart | Ad began to be viewable | | adTrust:viewableEnd | Ad is no longer viewable | | adTrust:viewableImpression | Ad has been viewable for required time | | adTrust:viewQuartile | Ad reached viewability quartile (25%, 50%, 75%, 100%) | | adTrust:click | Ad was clicked | | adTrust:videoReady | Video is ready to play | | adTrust:videoStart | Video started playing for the first time | | adTrust:videoPlay | Video started or resumed playing | | adTrust:videoPause | Video was paused | | adTrust:videoQuartile | Video reached playback quartile (25%, 50%, 75%) | | adTrust:videoComplete | Video completed playback | | adTrust:videoError | Error with video playback |

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.