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.

!Version

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

$3

``html

`

$3

`bash
npm install adtrust
`

Then import in your project:

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

Usage

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

$3

Add script tags with data attributes to define ads:

`html

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



data-type="html"
data-html-content="


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

`

$3

Create ads programmatically:

`javascript
// 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: "

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

| 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

$3

`javascript
// 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);
`

$3

`javascript
// 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:

`javascript
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:

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

$3

`html





`

$3

`javascript
// 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');
}
});
`

$3

`html





`

$3

AdTrust supports YouTube videos in video ads:

`javascript
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.