External Segments Provider Integration

Overview

This documentation provides technical details for integrating an external Data Management Platform (DMP) with our system. The integration enables partners to pass user segments created in their DMP to our advertising platform for targeted display and/or email marketing campaigns.

System Architecture

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

"lu:201905161437551994208900","['1', '2', '3']"
"lu:201905161437551994208902","['4']"
"aid:45721b293195c854cdc4f161e3129910","['1', '2']"
"aid:35721b293195c854cdc4f161e3129910","['1']"

Key Structure

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

Value Structure

• Segment IDs as JSON array of strings
• Example: ['1', '2', '3', '5']

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/
├── {network_id}/
│   ├── {YYYYMMDD}/
│   │   └── segments_file.csv
│   ├── {YYYYMMDD}/
│   │   └── segments_file.csv

Path Components

• First Level: ADP Network ID
• Second 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 Removal: Send empty list [] to remove all segment assignments
4. 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

Integration Testing

Required for Setup

• Network ID assignment
• S3 bucket access credentials

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