# 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](https://img.shields.io/badge/version-0.0.4-blue.svg)

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