adtrust
Version:
AdTrust is a versatile JavaScript library designed for efficient ad delivery with built-in viewability tracking, multi-format support, and ad block detection.
406 lines (314 loc) • 12.2 kB
Markdown
# 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)
```html
<script src="https://unpkg.com/adtrust"></script>
```
### Via NPM
```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.
### Declarative Implementation (HTML)
Add script tags with data attributes to define ads:
```html
<!-- 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:
```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: "<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
```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);
```
### Ad Instance Methods
```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
### Using HTML Templates
```html
<!-- 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
```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');
}
});
```
### Custom Container Placement
```html
<!-- 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:
```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](LICENSE)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.