# Ad Tech IDs Module

The Ad Tech IDs module detects advertising technology platforms and extracts their identifiers present on websites. This module is designed to provide visibility into the ad tech stack and user identifiers used by various advertising platforms.

## Overview

The module scans for:
- **Ad Tech Platforms**: Prebid, Google Publisher Tags (GPT), various SSPs and bidders
- **User IDs**: Universal IDs, bidder-specific IDs, and cookie-based identifiers
- **Configuration Data**: Timeouts, price granularity, enabled bidders, and more

## Supported Platforms

### Header Bidding
- **Prebid.js**: Version, configuration, user IDs, installed modules, enabled bidders
- **Amazon TAM/APS**: Presence detection
- **Index Exchange**: Presence detection and cookie IDs
- **OpenX**: Presence detection and cookie IDs

### Google
- **Google Publisher Tags (GPT)**: Slot counts, targeting keys, header bidding integration
- **Google Ads**: User identifiers (__gads, __gpi)
- **Google Funding Choices**: CMP detection

### SSPs/Bidders
- **Adform**: Platform detection and user IDs
- **AppNexus/Xandr**: Platform detection and user IDs
- **Criteo**: Platform detection and user IDs
- **ImproveDigital**: Platform detection and user IDs
- **LiveWrapped**: Platform detection and user IDs
- **OpenX**: Platform detection and user IDs
- **PubMatic**: Platform detection and user IDs
- **Rubicon**: Platform detection and user IDs
- **SmartAdServer**: User IDs
- **Sovrn/Lijit**: Platform detection and user IDs
- **Teads**: User IDs
- **TripleLift**: Platform detection and user IDs

### Universal IDs
- **SharedID**: Cookie and localStorage detection
- **PubCommon ID**: Cookie and localStorage detection
- **LiveRamp ATS/IDL**: Platform detection
- **ID5**: Platform detection and user IDs
- **Unified ID 2.0**: Platform detection and tokens
- **NetID**: Via Prebid
- **IdentityLink**: Via Prebid
- **LiveIntent**: Via Prebid
- **And many more**: Via Prebid's userId module

### Privacy & Consent
- **TCF API**: IAB Transparency & Consent Framework detection
- **Google Funding Choices**: Consent management platform

## Collected Signals

All signals use the `adtech_` prefix for consistency and clarity.

### Platform Detection Signals

```typescript
adtech_platform_prebid: "true"
adtech_platform_gpt: "true"
adtech_platform_criteo: "true"
adtech_platform_adform: "true"
// ... etc for each detected platform
```

### Prebid Signals

```typescript
adtech_prebid_version: "8.52.2"
adtech_prebid_timeout: "1200"
adtech_prebid_price_granularity: "custom"
adtech_prebid_bidders: "rubicon,appnexus,criteo,improvedigital"
adtech_prebid_bidders_count: "4"
adtech_prebid_modules_count: "15"
adtech_prebid_module_userId: "true"
adtech_prebid_module_consentManagement: "true"
adtech_prebid_s2s_enabled: "true"
```

### Prebid User IDs

```typescript
adtech_userid_pubcid: "a8d1c084-f148-4706-b948-b815d47a67dc"
adtech_userid_sharedid: "xyz123..."
adtech_userid_id5id: "ID5*abc..."
adtech_userid_identityLink: "def456..."
adtech_userid_criteo: "ghi789..."
// ... etc for all detected user ID modules
```

### GPT Signals

```typescript
adtech_gpt_slots_count: "5"
adtech_gpt_hb_keys_count: "17"
adtech_gpt_page_targeting_count: "8"
```

### Universal ID Signals

```typescript
adtech_universal_sharedid: "hashed_value"
adtech_universal_pubcid: "hashed_value"
adtech_universal_liveramp: "true"
adtech_universal_id5: "hashed_value"
adtech_universal_uid2: "true"
adtech_universal_uid2_token: "hashed_value"
```

### Bidder ID Signals

```typescript
adtech_bidder_criteo_id: "hashed_value"
adtech_bidder_rubicon_id: "hashed_value"
adtech_bidder_appnexus_id: "hashed_value"
adtech_bidder_livewrapped_id: "hashed_value"
// ... etc for all detected bidders
```

### Google Ads Signals

```typescript
adtech_google_gads_id: "hashed_value"
adtech_google_gpi_id: "hashed_value"
adtech_google_ga_id: "hashed_value"
```

## Usage

### Basic Usage

```typescript
const idGraph = new IdGraph('my-container', {
  modules: ['ad_tech_ids'],
  debug: true
});
```

### Combined with Other Modules

```typescript
const idGraph = new IdGraph('my-container', {
  modules: [
    'browser_info',
    'ad_tech_ids',
    'fingerprint_basic'
  ]
});
```

### Access Collected Signals

```typescript
// Get all signals
const signals = idGraph.getSignals();

// Filter ad tech signals
const adTechSignals = signals.filter(s => s.name.startsWith('adtech_'));

// Send signals
idGraph.flushSignals();
```

## Privacy Considerations

### Hashed Values

The module automatically hashes sensitive identifiers before storing them:
- User IDs from cookies
- Bidder-specific identifiers
- Universal ID tokens
- Google Ads identifiers

### Non-Hashed Values

The following are NOT hashed as they represent technical configuration, not user data:
- Platform presence indicators
- Version numbers
- Configuration values (timeouts, granularity)
- Counts (slots, bidders, modules)

### Data Minimization

The module follows data minimization principles:
- Only collects data that is already present on the page
- Hashes personal identifiers
- Does not create new identifiers
- Does not sync IDs with third parties

## Integration Examples

### Detecting Ad Tech Stack

```typescript
const idGraph = new IdGraph('my-container', {
  modules: ['ad_tech_ids']
});

// After collection, check what platforms are present
const signals = idGraph.getSignals();
const hasPrebid = signals.some(s => s.name === 'adtech_platform_prebid' && s.value === 'true');
const hasGPT = signals.some(s => s.name === 'adtech_platform_gpt' && s.value === 'true');

console.log('Prebid detected:', hasPrebid);
console.log('GPT detected:', hasGPT);
```

### Monitoring Bidder Activity

```typescript
const idGraph = new IdGraph('my-container', {
  modules: ['ad_tech_ids']
});

// Check which bidders are configured
const signals = idGraph.getSignals();
const biddersSignal = signals.find(s => s.name === 'adtech_prebid_bidders');
if (biddersSignal) {
  const bidders = biddersSignal.value.split(',');
  console.log('Active bidders:', bidders);
}
```

### Universal ID Detection

```typescript
const idGraph = new IdGraph('my-container', {
  modules: ['ad_tech_ids']
});

const signals = idGraph.getSignals();
const hasSharedId = signals.some(s => s.name === 'adtech_universal_sharedid');
const hasUID2 = signals.some(s => s.name === 'adtech_universal_uid2');

console.log('SharedID available:', hasSharedId);
console.log('UID 2.0 available:', hasUID2);
```

## Technical Details

### Detection Methods

1. **JavaScript API Detection**: Checks for global objects like `window.pbjs`, `window.googletag`
2. **DOM Scanning**: Searches for script tags and iframes from known vendors
3. **Cookie Reading**: Extracts identifiers from first-party cookies
4. **localStorage Access**: Checks localStorage for stored IDs

### Timing Considerations

The module collects data asynchronously to handle:
- Prebid queue processing
- GPT command queue execution
- Delayed script loading
- Dynamic ad unit creation

### Error Handling

The module includes comprehensive error handling:
- Gracefully handles missing APIs
- Catches and logs exceptions
- Continues collection even if one platform fails
- Returns empty values for unavailable data

## Troubleshooting

### No Signals Collected

If no ad tech signals are being collected:

1. **Check Timing**: Ensure the module runs after ad tech scripts have loaded
2. **Verify Platforms**: Check browser console to confirm ad tech platforms are present
3. **Enable Debug Mode**: Set `debug: true` to see module activity
4. **Check Privacy Settings**: Some privacy tools block ad tech detection

### Missing Platform Detection

If a platform is present but not detected:

1. **Script Load Order**: Ad tech scripts may load after the module runs
2. **Custom Implementation**: The site may use a custom wrapper or different global variable
3. **Obfuscation**: Some implementations use obfuscated or non-standard names

### Debug Mode

Enable debug logging to see module activity:

```typescript
const idGraph = new IdGraph('my-container', {
  modules: ['ad_tech_ids'],
  debug: true
});
```

Debug messages appear in the console with an orange "AdTechIds Module" badge.

## Performance Impact

The module is designed to have minimal performance impact:

- **Execution Time**: < 50ms typically
- **Memory**: < 100KB
- **Network**: No additional requests
- **DOM Access**: Read-only operations

## Browser Compatibility

The module is compatible with:
- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

Legacy browsers may have limited functionality but won't cause errors.

## Related Modules

- **browser_info**: Collects browser and device information
- **fingerprint_basic**: Creates basic browser fingerprints
- **1stparty_cookie**: Manages first-party cookie identifiers
- **utm_params**: Tracks campaign parameters

## Contributing

To add support for a new ad tech platform:

1. Add detection logic in `detectPlatforms()`
2. Create extraction method (e.g., `extractPlatformData()`)
3. Add cookie/localStorage keys if applicable
4. Update documentation
5. Add test cases

## References

- [Prebid.js Documentation](https://docs.prebid.org/)
- [Google Publisher Tags Reference](https://developers.google.com/publisher-tag/reference)
- [IAB TCF 2.0 Specification](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework)
- [Prebid User ID Modules](https://docs.prebid.org/dev-docs/modules/userId.html)