Event Groups

​

Overview

​

What is an EventGroup?

• Advertising Campaign: All impressions for a specific campaign
• Creative: All views of a particular creative asset
• App Install Campaign: All app install events from a promotion
• Content Episode: All watch events for a TV episode
• Publisher Inventory: All ad events on a specific website

​

Resource Definition

message EventGroup {
  option (google.api.resource) = {
    type: "halo.wfanet.org/EventGroup"
    pattern: "dataProviders/{data_provider}/eventGroups/{event_group}"
    pattern: "measurementConsumers/{measurement_consumer}/eventGroups/{event_group}"
  };

  string name = 1;
  string measurement_consumer = 2;  // Required, immutable
  string event_group_reference_id = 5;
  repeated MediaType media_types = 13;
  EventGroupMetadata event_group_metadata = 14;
  repeated EventTemplate event_templates = 7;
  EncryptedMessage encrypted_metadata = 10;
  google.type.Interval data_availability_interval = 11;
  State state = 9;
}

• Canonical: dataProviders/{data_provider}/eventGroups/{event_group}
• Alternative: measurementConsumers/{measurement_consumer}/eventGroups/{event_group}

​

Core Fields

​

MeasurementConsumer Association

string measurement_consumer = 2 [
  (google.api.resource_reference).type = "halo.wfanet.org/MeasurementConsumer",
  (google.api.field_behavior) = REQUIRED,
  (google.api.field_behavior) = IMMUTABLE
];

• Required at creation and cannot be changed
• Links events to the entity that can measure them
• Enables access control and data governance
• Supports multi-tenant data sharing

​

Event Group Reference ID

string event_group_reference_id = 5;

• External identifier from DataProvider’s system
• Helps DataProviders synchronize metadata
• Not used for API operations (use resource name instead)
• Useful for debugging and reconciliation

​

Media Types

repeated MediaType media_types = 13;

enum MediaType {
  MEDIA_TYPE_UNSPECIFIED = 0;
  VIDEO = 1;
  DISPLAY = 2;
  AUDIO = 3;
  // ... additional types
}

• Determines compatible EventTemplates
• Enables media-specific filtering
• Supports cross-media attribution

​

Event Templates

message EventTemplate {
  string type = 1;  // Fully-qualified protobuf message type
}

repeated EventTemplate event_templates = 7;

• Defines the schema of events in this EventGroup
• Specifies which protobuf message types represent events
• Enables type-safe event processing

event_templates {
  type: "wfa.measurement.api.v2alpha.event.ImpressionEvent"
}

​

Data Availability Interval

google.type.Interval data_availability_interval = 11;

message Interval {
  google.protobuf.Timestamp start_time = 1;  // Required
  google.protobuf.Timestamp end_time = 2;    // Optional for unbounded
}

• start_time: When events began (campaign start date)
• end_time: When events ended (campaign end date, or omitted if ongoing)
• Events outside this interval are not available for measurement

• Ad Campaign: Start and end dates of campaign flight
• TV Series: Premiere date to finale date
• Ongoing Service: Start date with no end date

​

Event Group Metadata

​

Encrypted Metadata

message Metadata {
  string event_group_metadata_descriptor = 1;
  google.protobuf.Any metadata = 2;
}

EncryptedMessage encrypted_metadata = 10;

1. DataProvider creates Metadata message
2. Serializes metadata using descriptor
3. Encrypts using MeasurementConsumer’s public key
4. Sets encrypted_metadata field

• Campaign details (name, advertiser, budget)
• Creative attributes (format, dimensions)
• Targeting criteria (demographics, interests)
• Custom business metadata

​

Public Metadata (EventGroupMetadata)

EventGroupMetadata event_group_metadata = 14;

message EventGroupMetadata {
  // Example fields from event_group_metadata.proto
  // Specific structure depends on implementation
}

• Publicly shareable attributes
• System-level metadata
• Searchable/filterable properties

​

Metadata Descriptors

• Define custom metadata structures
• Enable type-safe metadata handling
• Support evolution of metadata schemas

​

State Lifecycle

enum State {
  STATE_UNSPECIFIED = 0;
  ACTIVE = 1;
  DELETED = 2;  // Terminal state
}

​

ACTIVE

• EventGroup is available for measurements
• Can be referenced in RequisitionSpecs
• Metadata can be updated

​

DELETED

• EventGroup has been deleted
• All mutable optional fields are cleared
• Cannot be used in new measurements
• Terminal state - cannot be reactivated

​

Creating an EventGroup

​

Required Fields

1. measurement_consumer: Resource name of associated MeasurementConsumer
2. media_types: At least one media type
3. event_group_metadata: Public metadata
4. data_availability_interval.start_time: When events begin

​

Optional Fields

1. event_group_reference_id: Your external identifier
2. event_templates: Event schema definitions
3. encrypted_metadata: Private metadata for MeasurementConsumer
4. measurement_consumer_public_key: For encrypting metadata
5. data_availability_interval.end_time: When events end (if bounded)

{
  "measurement_consumer": "measurementConsumers/abc123",
  "media_types": ["VIDEO"],
  "event_group_reference_id": "campaign-2024-q1-video",
  "data_availability_interval": {
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-03-31T23:59:59Z"
  },
  "event_templates": [
    {"type": "wfa.measurement.api.v2alpha.event.ImpressionEvent"}
  ]
}

​

Using EventGroups in Measurements

message RequisitionSpec {
  message EventGroupEntry {
    string key = 1;  // EventGroup resource name
    
    message Value {
      google.type.Interval collection_interval = 1;
      EventFilter filter = 2;
    }
    Value value = 2;
  }
  repeated EventGroupEntry event_groups = 1;
}

​

Collection Interval

google.type.Interval collection_interval = 1;

• Collection interval should fall within data_availability_interval
• Can be narrower than availability (query subset of time)
• If outside availability, DataProvider may refuse requisition

• EventGroup availability: 2024-01-01 to 2024-12-31 (full year)
• Measurement collection: 2024-01-01 to 2024-01-31 (January only)

​

Event Filters

EventFilter filter = 2;

• Filter by creative ID
• Filter by geographic region
• Filter by device type
• Custom attribute filtering

​

Aggregated Activity

message AggregatedActivity {
  DateInterval interval = 1;
}

repeated AggregatedActivity aggregated_activities = 15;

• Provide summary statistics about event activity
• Help MeasurementConsumers understand data availability
• Enable trend analysis

​

EventGroup Views

enum View {
  VIEW_UNSPECIFIED = 0;
  BASIC = 1;
  WITH_ACTIVITY_SUMMARY = 2;
}

• Standard fields only
• No aggregated_activities
• Faster, less data transfer

• Includes aggregated_activities field
• Provides activity summaries
• More data transfer

​

Best Practices

​

EventGroup Design

1. Logical Grouping: Group events by meaningful business units (campaigns, creatives, etc.)
2. Granularity: Not too broad (all events) or too narrow (one event per group)
3. Stability: Avoid frequent creation/deletion; update existing EventGroups when possible
4. Naming: Use descriptive event_group_reference_id for easy identification

​

Metadata Management

1. Encrypt Sensitive Data: Use encrypted_metadata for proprietary information
2. Public Metadata: Use event_group_metadata for non-sensitive, searchable attributes
3. Schema Evolution: Use EventGroupMetadataDescriptors to manage schema changes
4. Key Management: Securely manage encryption keys for metadata

​

Data Availability

1. Accurate Intervals: Set data_availability_interval to match actual data retention
2. Update Intervals: Update end_time when campaigns conclude
3. Buffer Time: Consider data pipeline delays when setting availability
4. Unbounded Groups: Use open-ended intervals for ongoing data collection

​

Performance

1. Batch Creation: Create multiple EventGroups in parallel when possible
2. Listing Optimization: Use filters and field masks to reduce response size
3. View Selection: Only request WITH_ACTIVITY_SUMMARY when needed
4. Caching: Cache EventGroup metadata locally to reduce API calls

​

Common Patterns

​

Campaign-Based EventGroups

One EventGroup per advertising campaign
├── Contains all impressions for the campaign
├── data_availability_interval = campaign flight dates
├── encrypted_metadata = campaign details (advertiser, budget, etc.)
└── Can be measured independently or combined with other campaigns

​

Publisher Inventory EventGroups

One EventGroup per publisher property
├── Contains all ad events on that property
├── data_availability_interval = ongoing (no end_time)
├── event_group_metadata = property attributes (category, audience)
└── Measurements query specific time ranges via collection_interval

​

Content-Based EventGroups

One EventGroup per content item (video, article, etc.)
├── Contains all view/engagement events for that content
├── data_availability_interval = publication date to archive date
├── metadata = content attributes (title, genre, duration)
└── Enables content performance analysis

​

Troubleshooting

​

EventGroup Not Usable in Measurement

• EventGroup state is DELETED
• measurement_consumer doesn’t match Measurement owner
• collection_interval outside data_availability_interval
• Incompatible media_types or event_templates

​

Metadata Decryption Fails

• Wrong encryption key used
• MeasurementConsumer public key rotated
• Corrupted encrypted_metadata
• Version mismatch in encryption format

​

Requisition Refused

• collection_interval significantly outside data_availability_interval
• Event data not yet available (pipeline delay)
• EventGroup deleted after Measurement creation
• Invalid event filters

​

Related Concepts

• Measurements - How EventGroups are used in measurements
• Resource Model - EventGroup’s place in the resource hierarchy
• Differential Privacy - Privacy protection for event data