diff --git a/dev-docs/modules/scope3RtdProvider.md b/dev-docs/modules/scope3RtdProvider.md new file mode 100644 index 0000000000..c2e433fadd --- /dev/null +++ b/dev-docs/modules/scope3RtdProvider.md @@ -0,0 +1,215 @@ +--- +layout: page_v2 +title: Scope3 RTD Provider +display_name: Scope3 RTD Provider +description: Scope3 Real-Time Data Provider for Prebid.js +page_type: module +module_type: rtd +module_code: scope3RtdProvider +enable_download: true +vendor_specific: true +sidebarType: 1 +--- + +# Scope3 RTD Provider + +The Scope3 RTD (Real-Time Data) Provider enables publishers to leverage Scope3's Agentic Execution Engine (AEE) for real-time media buying optimization. This module sends complete OpenRTB requests to Scope3 and receives contextual signals that enhance auction targeting. + +{:.no_toc} + +* TOC +{:toc} + +## Overview + +The Scope3 RTD Provider: + +* Sends complete OpenRTB 2.x requests including extended UIDs, geo data, and device information +* Receives AEE signals for include/exclude targeting and macros +* Supports bidder-specific segments and deal IDs +* Enables configurable GAM targeting keys +* Works client-side without API keys + +## Usage + +### Basic Configuration + +```javascript +pbjs.setConfig({ + realTimeData: { + auctionDelay: 100, + dataProviders: [{ + name: "scope3RtdProvider", + waitForIt: true, + params: { + orgId: "your-org-id" + } + }] + } +}); +``` + +### Full Configuration + +```javascript +pbjs.setConfig({ + realTimeData: { + auctionDelay: 200, + dataProviders: [{ + name: "scope3RtdProvider", + waitForIt: true, + params: { + orgId: "your-org-id", + endpoint: "", + timeout: 1500, + bidders: ["appnexus", "rubicon", "pubmatic"], + includeKey: "scope3_include", + excludeKey: "scope3_exclude", + macroKey: "scope3_macro", + publisherTargeting: true, + advertiserTargeting: true, + cacheEnabled: true, + cacheTtl: 300000 + } + }] + } +}); +``` + +## Configuration Parameters + +{: .table .table-bordered .table-striped } + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| orgId | String | Yes | Your Scope3 organization ID | +| endpoint | String | No | API endpoint (default: `https://prebid.scope3.com/prebid`) | +| timeout | Number | No | Request timeout in milliseconds (default: 1000) | +| bidders | Array | No | List of bidders to target (default: all auction bidders) | +| includeKey | String | No | GAM targeting key for include signals (default: "scope3_include") | +| excludeKey | String | No | GAM targeting key for exclude signals (default: "scope3_exclude") | +| macroKey | String | No | GAM targeting key for macro data (default: "scope3_macro") | +| publisherTargeting | Boolean | No | Enable publisher-level targeting (default: true) | +| advertiserTargeting | Boolean | No | Enable advertiser-level targeting (default: true) | +| cacheEnabled | Boolean | No | Enable response caching (default: true) | +| cacheTtl | Number | No | Cache TTL in milliseconds (default: 300000) | + +## Response Format + +The Scope3 AEE returns signals in this format: + +```json +{ + "aee_signals": { + "include": ["sports_fan", "auto_intender"], + "exclude": ["competitor_exposed"], + "macro": "eyJjb250ZXh0IjogImhpZ2hfdmFsdWUifQ==", + "bidders": { + "appnexus": { + "segments": ["seg1", "seg2"], + "deals": ["DEAL123"] + }, + "rubicon": { + "segments": ["seg3"], + "deals": [] + } + } + } +} +``` + +## GAM Integration + +### Line Item Setup + +Create GAM line items with key-value targeting using the configured keys: + +**Include Targeting:** + +* Key: `scope3_include` (or your configured includeKey) +* Values: `sports_fan`, `auto_intender`, etc. +* Operator: "is any of" + +**Exclude Targeting:** + +* Key: `scope3_exclude` (or your configured excludeKey) +* Values: `competitor_exposed`, etc. +* Operator: "is none of" + +**Macro Targeting:** + +* Key: `scope3_macro` (or your configured macroKey) +* Values: Base64-encoded contextual data + +### Example Line Item Configuration + +```text +Creative: 300x250 Banner +Targeting: + * scope3_include is any of "sports_fan", "auto_intender" + * scope3_exclude is none of "competitor_exposed" + * scope3_macro is "eyJjb250ZXh0IjogImhpZ2hfdmFsdWUifQ==" +``` + +## Data Flow + +1. **Request**: Module sends complete OpenRTB request to Scope3 including: + * All extended user IDs + * Geo and device data + * Ad unit configurations + * Bidder list + +2. **Processing**: Scope3's AEE analyzes the request context + +3. **Response**: AEE returns targeting signals: + * Global include/exclude segments + * Bidder-specific segments and deals + * Contextual macro data + +4. **Application**: Module applies signals to bid request: + * Global targeting in `ortb2Fragments.global.site.ext.data` + * Bidder segments in `ortb2Fragments.bidder[].user.data` + * Deal IDs in ad unit `ortb2Imp.ext` + +## Testing + +### Integration Testing + +Use the Hello World example to verify integration: + +1. Configure the module with your orgId +2. Monitor network requests to confirm data is sent +3. Check that targeting data appears in bid requests +4. Verify GAM line items receive the targeting keys + +### Debug Mode + +Enable Prebid debug mode to see targeting data: + +```javascript +pbjs.debug = true; +``` + +Check the browser console for RTD provider logs and bid request modifications. + +## Privacy Considerations + +The Scope3 RTD Provider: + +* Respects user consent choices +* Only processes data necessary for contextual targeting +* Does not store personal information +* Complies with privacy regulations when properly configured + +## Support + +For questions about the Scope3 RTD Provider: + +* Technical issues: Open a GitHub issue in the Prebid.js repository +* Integration support: Contact your Scope3 representative +* Documentation: Submit PRs to improve this documentation + +## Related Modules + +* [Real-Time Data Module]({{site.baseurl}}/dev-docs/modules/realTimeData.html) +* [RTD Sub-Module Development]({{site.baseurl}}/dev-docs/add-rtd-submodule.html) diff --git a/prebid-server/pbs-modules/scope3-real-time-data.md b/prebid-server/pbs-modules/scope3-real-time-data.md new file mode 100644 index 0000000000..df5f876dac --- /dev/null +++ b/prebid-server/pbs-modules/scope3-real-time-data.md @@ -0,0 +1,262 @@ +--- +layout: page_v2 +title: Prebid Server Scope3 Real Time Data Module +display_name: Scope3 Real Time Data Module +description: Scope3 RTD module for Prebid Server +sidebarType: 5 +--- + +# Scope3 Real Time Data Module +{:.no_toc} + +* TOC +{:toc} + +## Overview + +The Scope3 Real Time Data (RTD) module integrates Scope3's Agentic Execution Engine to provide real-time audience segments and contextual signals for programmatic advertising. This module enables publishers to leverage Scope3's AI-driven targeting capabilities directly within Prebid Server auctions. + +## Features + +* **Real-time Segmentation**: Fetches audience segments from Scope3's API in real-time +* **Identity Integration**: Works with LiveRamp, publisher IDs, and encrypted identity envelopes +* **Intelligent Caching**: Thread-safe caching with configurable TTL to optimize performance +* **Flexible Output**: Segments available in response for publisher control +* **GAM Integration**: Optional direct targeting key population for Google Ad Manager +* **Error Resilience**: Graceful degradation without blocking auctions + +## Installation + +To enable this module, compile Prebid Server with: + +```bash +go build -tags scope3_rtd +``` + +Or include in your Docker build: + +```dockerfile +RUN go build -tags scope3_rtd +``` + +## Configuration + +### Basic Configuration + +```yaml +hooks: + enabled: true + modules: + scope3: + rtd: + enabled: true + auth_key: ${SCOPE3_API_KEY} + timeout_ms: 1000 +``` + +### Full Configuration + +```yaml +hooks: + enabled: true + modules: + scope3: + rtd: + enabled: true + auth_key: ${SCOPE3_API_KEY} + timeout_ms: 1000 + cache_ttl_seconds: 60 + add_to_targeting: false + host_execution_plan: + endpoints: + /openrtb2/auction: + stages: + entrypoint: + groups: + - timeout: 5 + hook_sequence: + - module_code: "scope3.rtd" + hook_impl_code: "HandleEntrypointHook" + raw_auction_request: + groups: + - timeout: 2000 + hook_sequence: + - module_code: "scope3.rtd" + hook_impl_code: "HandleRawAuctionHook" + auction_response: + groups: + - timeout: 5 + hook_sequence: + - module_code: "scope3.rtd" + hook_impl_code: "HandleAuctionResponseHook" +``` + +### Configuration Parameters + +{: .table .table-bordered .table-striped } + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| enabled | boolean | Yes | - | Enable/disable the module | +| auth_key | string | Yes | - | Scope3 API authentication key | +| timeout_ms | int | No | 1000 | API request timeout in milliseconds | +| cache_ttl_seconds | int | No | 60 | Cache duration in seconds | +| add_to_targeting | boolean | No | false | Add segments as GAM targeting keys | + +## Identity Support + +The module automatically detects and forwards available user identifiers: + +### LiveRamp Identifiers + +* `user.ext.eids[]` with `source: "liveramp.com"` +* `user.ext.rampid` field + +### Encrypted Identity Envelopes + +* `user.ext.liveramp_idl` - ATS envelope +* `user.ext.ats_envelope` - Alternative envelope location +* `user.ext.rampId_envelope` - Additional envelope location +* `ext.liveramp_idl` - Request-level envelope + +### Standard Identifiers + +* `user.id` - Publisher user ID +* `device.ifa` - Device advertising ID +* Other OpenRTB standard identifiers + +## Response Format + +### Standard Response +Segments are always available in the response extension: + +```json +{ + "ext": { + "scope3": { + "segments": ["gmp_eligible", "high_value_user", "sports_fan"] + } + } +} +``` + +### With GAM Targeting (add_to_targeting: true) +When enabled, segments are also added as targeting keys: + +```json +{ + "ext": { + "prebid": { + "targeting": { + "gmp_eligible": "true", + "high_value_user": "true", + "sports_fan": "true" + } + }, + "scope3": { + "segments": ["gmp_eligible", "high_value_user", "sports_fan"] + } + } +} +``` + +## Performance Optimization + +### Caching Strategy + +* **Cache Key**: Generated from user IDs, domain, and page URL +* **Thread Safety**: Read-write mutexes for concurrent access +* **Memory Efficiency**: Stores only segment arrays +* **Frequency Caps**: 60-second default TTL ensures fresh data + +### HTTP Optimization + +* Connection pooling with keep-alive +* HTTP/2 support when available +* Gzip compression for responses +* Configurable timeouts + +## Integration Examples + +### Google Ad Manager +Publishers can use segments for GAM targeting: + +```javascript +// Client-side code to read Scope3 segments +pbjs.getBidResponses().forEach(response => { + const segments = response.ext?.scope3?.segments || []; + // Forward to GAM targeting +}); +``` + +### Custom Ad Servers +Access segments from the auction response: + +```go +// Server-side handling +segments := response.Ext["scope3"]["segments"] +// Forward to your ad server +``` + +## Monitoring + +The module logs important events at different levels: + +* **INFO**: Successful segment fetches and cache hits +* **WARN**: API timeouts or non-critical errors +* **ERROR**: Configuration issues or critical failures + +Example log entries: + +```text +INFO: Scope3 RTD: Fetched 3 segments for user +WARN: Scope3 RTD: API timeout after 1000ms +INFO: Scope3 RTD: Cache hit for key abc123 +``` + +## Troubleshooting + +### No Segments Returned + +1. Verify API key is correctly configured +2. Check endpoint URL accessibility +3. Ensure user identifiers are present in bid request +4. Review server logs for API errors + +### Performance Issues + +1. Adjust `timeout_ms` based on network latency +2. Increase `cache_ttl_seconds` for less frequent updates +3. Monitor cache hit rates in logs +4. Check API response times + +### Configuration Errors + +1. Validate YAML/JSON syntax +2. Ensure environment variables are set +3. Check module is compiled into PBS binary +4. Verify hook execution plan is correct + +## Privacy Compliance + +The module respects privacy signals: + +* Honors GDPR consent strings +* Respects US Privacy (CCPA) signals +* Does not process requests when consent is denied +* Only forwards consented identifiers to Scope3 + +## Support + +For technical support: + +* **Issues**: Open a GitHub issue in the Prebid Server repository +* **Documentation**: Submit PRs to improve this documentation +* **Integration Help**: Contact your Scope3 representative +* **Email**: `bokelley@scope3.com` + +## Related Documentation + +* [Prebid Server Modules]({{site.baseurl}}/prebid-server/pbs-modules/) +* [Module Development]({{site.baseurl}}/prebid-server/developers/add-a-module.html) +* [Real-Time Data Overview]({{site.baseurl}}/prebid-server/features/pbs-rtd.html)