DAS DMP Integration Guide

Overview

This documentation provides technical details for integrating a Data Management Platform (DMP) with our Dream Adserver (DAS) system. The integration enables partners to pass user segments created in their DMP to our advertising platform for targeted email marketing campaigns.

System Architecture

Dream Adserver (DAS) is part of the Ring DAS ecosystem that delivers display and email advertisements. The platform utilizes two primary user identifiers:

• LU (Local User): Browser-based identifier stored in third-party cookies
• AID (Advertiser ID): Hashed email identifier for logged-in users

User Identification System

LU (Local User) Identifier

• Format: Date-based prefix + unique identifier
• Example: 201905161437551994208900
• Storage: Third-party cookies
• Purpose: Browser-based user tracking

AID (Advertiser ID)

• Format: Hashed user email
• Example: 45721b293195c854cdc4f161e3129910
• Purpose: Logged-in user identification across sign-in systems
• Note: Segments must be assigned separately for AID and LU even for the same user

Integration Methods

1. Key-Value Integration

The primary integration method uses key-value pairs to map user identifiers to segment lists.

Data Format

# Adding segments
"aid:60225704e0dab8df3fcf0ab7fd7fb366","['1181']"
"lu:201905161437551994208900","['1', '2', '3']"

# Removing specific segments (using negative IDs)
"lu:202512061231312560201331","['-1192','-1181','-1360','-1120']"

# Mixed operations (add 1181, remove 1192)
"lu:123456789","['1181','-1192']"

Key Structure

• LU Format: lu:{identifier}
• AID Format: aid:{identifier}

Value Structure

• Segment IDs as JSON array of strings
• Positive IDs: Add segments (e.g., ['1', '2', '3'])
• Negative IDs: Remove segments (e.g., ['-1181', '-1192'])
• Mixed Operations: Combine additions and removals (['1181', '-1192'])

2. PPID Integration

For Publisher Provided Identifier scenarios, maintain the same key-value structure with appropriate identifier mapping.

3. AID for Mailing Campaigns

AID identifiers are specifically used for email marketing campaigns, enabling cross-device user tracking through logged-in sessions.

AWS S3 Bucket Structure

Bucket Organization

adpaudbucket-for-external-provider/
├── {provider_name}/
│   ├── {network_id}/
│   │   ├── {YYYYMMDD}/
│   │   │   └── segments_file.csv

Path Components

• First Level: Provider name (your DMP provider identifier)
• Second Level: ADP Network ID
• Third Level: Date in YYYYMMDD format
• File: CSV containing segment assignments

File Processing Configuration

Processing Arguments

Add configuration lines at the beginning of CSV files to modify processing behavior:

set argument_name

Available Arguments

• not_extend_existing: Prevents extension of existing segment memberships; only adds new segments

Processing Rules

1. Missing Records: If no record exists for LU/AID, current segments remain unchanged
2. Complete Segment Lists: Include all current segments in each file
3. Segment Operations:
   • Negative IDs: ['-1181', '-1192'] removes specific segments
   • Remove All: Send negative IDs for all currently assigned segments
   • Mixed Operations: ['1181', '-1192'] adds 1181 and removes 1192
   • Skip User: Omit user from file entirely to leave segments unchanged
4. Segment Validation: Negative segment IDs are validated against their positive counterparts
5. Segment Limits: Maximum 10,000 segments per user (configurable)
6. Segment Expiration: Segments older than 60 days are automatically removed
7. Compaction: When user has >200 segment differences, system compacts old segments
8. Optimization: Exclude records unchanged for 60+ days to reduce file size

Cookie Matching Requirements

User Matching Process

Implement cookie matching by sending ADP user identifiers (LU, AID) via integration pixel to your DMP system.

Recommended Flow

1. User visits publisher site
2. Publisher collects LU/AID identifiers
3. Identifiers sent to DMP via pixel integration
4. DMP maps identifiers to internal user profiles
5. Segment assignments returned via S3 delivery

Segment Management

Creating Audience Segments

Before delivering segment data, segments must be defined in the ADP system using our GraphQL API.

GraphQL Mutation Example

mutation setAudienceSegment($audience_segment: IMAudienceSegmentInput!) {
  dream_audience {
    set_audience_segment(audience_segment: $audience_segment) {
      audience_segment_id
    }
  }
}

Variables Example

{
  "audience_segment": {
    "audience_segment_id": null,
    "audience_segment_expire": 5184000,
    "audience_segment_name": "Business News Junkies",
    "audience_segment_status": "ACTIVE",
    "audience_segment_type": "STATIC",
    "audience_segment_description": "Users frequently browsing business content"
  }
}

Querying Audience Segments

query audience_segments($limit: Int = 2, $offset: Int = 0, $sort: JSON, $filter: JSON) {
  dream_audience {
    audience_segments(limit: $limit, offset: $offset, filter: $filter, sort: $sort) {
      total_count
      edges {
        audience_segment_id
        audience_segment_name
        audience_segment_description
        audience_segment_status
        audience_segment_type
        audience_segment_membership_expire {
          value
          name
        }
      }
    }
  }
}

Archive Audience Segment

mutation archiveAudienceSegment($id: Int!) {
  dream_audience {
    archive_audience_segment(object_id: $id)
  }
}

Data Delivery Specifications

File Format

• Type: CSV (Comma Separated Values)
• Example filename: segments_file.csv

Data Requirements

• Identifier Validation: Ensure LU/AID format compliance
• Segment ID Validation: Verify segment IDs exist in ADP system

Processing Schedule

• Frequency: Hourly processing
• Latency: 7-hour delay due to data availability

Error Handling

Common Issues

1. Invalid Identifiers: Malformed LU/AID identifiers
2. Unknown Segments: Segment IDs not defined in ADP system
3. File Format Errors: Invalid CSV structure or encoding
4. Access Permissions: S3 bucket access issues

Data Export for DMP Enhancement

S3 Data-Ingest Access

External DMP providers can enhance their user profiling and segmentation by accessing event data from our data export system.

Available Event Data

The system exports aggregated event data including:

• Click events from Google Ad Manager and Ring AdServer (DAS)
• Open events for email campaigns
• Campaign metadata including advertiser, deal, lineitem, and creative information

Data Structures

Ads Data (export_1px)

export_1px(
  lu string,                 // Local User identifier
  aid string,                // Advertiser ID (hashed email)
  event string,              // Event type (click, open)
  event_timestamp timestamp, // Event occurrence time
  advertiser_name string,    // Advertiser information
  deal_name string,         // Deal information
  lineitem_name string,     // Line item details
  creative_name string,     // Creative information
  lineitem_id string,       // Line item ID
  site string,              // Publisher site
  slot string,              // Ad slot information
  type string,              // Event type classification
  category string,          // Content category
  brand string              // Brand information
)

Conversions Activities Data (export_1px_conversions_activities)

export_1px_conversions_activities(
  data_source string,        // Data source identifier
  lu string,                 // Local User identifier
  aid string,                // Advertiser ID (hashed email)
  event_type string,         // Type of conversion event
  event_timestamp bigint,    // Event occurrence timestamp
  lineitem_id string,        // Line item identifier
  lineitem_name string,      // Line item name
  creative_id string,        // Creative identifier
  creative_name string,      // Creative name
  deal_id string,           // Deal identifier
  deal_name string,         // Deal name
  advertiser_id string,     // Advertiser identifier
  advertiser_name string,   // Advertiser name
  product_quantity int,     // Quantity of products
  site_type string,         // Type of site
  basket_quantity double,   // Basket quantity
  product_id string,        // Product identifier
  product_price int,        // Product price
  product_name string,      // Product name
  product_brand string,     // Product brand
  product_category string,  // Product category
  activity_id int,          // Activity identifier
  activity_name string      // Activity name
)

S3 Data Locations

data-ingest/
├── ads_data/
│   ├── d_date_id=YYYYMMDD/
│   │   ├── d_hour_id=HH/
│   │   │   └── ad_data_YYYYMMDD_HH.parquet
│   │   └── conversions_activities_data/
│   │       └── d_hour_id=HH/
│   │           └── conversions_activities_data_YYYYMMDD_HH.parquet
└── prg_data/
    └── bidder/
        └── d_date_id=YYYYMMDD/
            └── bidder_data_YYYYMMDD.snappy.parquet

Data Characteristics

• Processing Frequency: Hourly
• Data Latency: 7-hour delay due to data availability requirements
• Partitioning: By date and hour for efficient querying

Typical Data Volume

• Average hourly records: Varies by event type and traffic
• File Format: Compressed Parquet files for optimal storage and processing

Integration Benefits

By accessing both segment delivery (via primary S3 bucket) and event consumption data (via data-ingest), DMP providers can:

1. Close the Loop: Match delivered segments with actual user behavior
2. Optimize Segmentation: Refine user profiles based on engagement patterns
3. Performance Analysis: Evaluate segment effectiveness across campaigns
4. Cross-Channel Insights: Combine display and email campaign performance

Access Requirements

• Separate S3 Credentials: Data-ingest access requires additional permissions
• Regional Considerations: Files are processed across multiple AWS regions
• Data Retention: Historical data availability varies by retention policies

Integration Testing

Required for Setup

• Network ID assignment
• S3 bucket access credentials (segment delivery)
• S3 data-ingest access credentials (event data)

Note: Specific testing procedures and support details should be provided by the ADP team during onboarding.