Event Groups API

​

Resource

​

EventGroup

• dataProviders/{data_provider}/eventGroups/{event_group} (canonical)
• measurementConsumers/{measurement_consumer}/eventGroups/{event_group}

​

EventTemplate

​

AggregatedActivity

​

View Enum

• VIEW_UNSPECIFIED - The default/unset value. The API will default to the BASIC view unless otherwise specified by the method.
• BASIC - Basic view
• WITH_ACTIVITY_SUMMARY - View with activity summary

​

Methods

​

GetEventGroup

message GetEventGroupRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
  EventGroup.View view = 2;
}

​

CreateEventGroup

message CreateEventGroupRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  EventGroup event_group = 2 [(google.api.field_behavior) = REQUIRED];
  string request_id = 3;
}

​

BatchCreateEventGroups

message BatchCreateEventGroupsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  repeated CreateEventGroupRequest requests = 2 [(google.api.field_behavior) = REQUIRED];
}

message BatchCreateEventGroupsResponse {
  repeated EventGroup event_groups = 1;
}

​

UpdateEventGroup

message UpdateEventGroupRequest {
  EventGroup event_group = 1 [(google.api.field_behavior) = REQUIRED];
}

• This performs a full replacement update.
• Partial updates are not supported.
• The name field identifies which EventGroup to update.
• Immutable fields cannot be changed.

​

BatchUpdateEventGroups

message BatchUpdateEventGroupsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  repeated UpdateEventGroupRequest requests = 2 [(google.api.field_behavior) = REQUIRED];
}

message BatchUpdateEventGroupsResponse {
  repeated EventGroup event_groups = 1;
}

​

DeleteEventGroup

message DeleteEventGroupRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

• Deletion is irreversible.
• The EventGroup transitions to DELETED state (terminal).
• All mutable optional fields are cleared.
• The resource remains visible but cannot be used in new measurements.

​

ListEventGroups

message ListEventGroupsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  int32 page_size = 2;
  string page_token = 3;
  Filter filter = 4;
  bool show_deleted = 5;
  OrderBy order_by = 6;
  EventGroup.View view = 7;
}

message ListEventGroupsResponse {
  repeated EventGroup event_groups = 1;
  string next_page_token = 2;
}

​

Workflow

​

Creating Event Groups

1. Identify Event Source: Determine which campaign or data source the EventGroup represents.
2. Prepare Metadata: Collect metadata about the events (campaign info, creative details, etc.).
3. Set Media Types: Specify which MediaTypes the events conform to.
4. Define Availability: Set the data_availability_interval for when events are available.
5. Associate Consumer: Specify which MeasurementConsumer this EventGroup is shared with.
6. Create Resource: Call CreateEventGroup or BatchCreateEventGroups.

​

Updating Event Groups

1. Retrieve Current State: Use GetEventGroup to get the current EventGroup.
2. Modify Fields: Update the fields you want to change.
3. Submit Update: Call UpdateEventGroup with the complete updated resource.
4. Verify Changes: Optionally call GetEventGroup again to confirm the update.

​

Deleting Event Groups

1. Identify EventGroup: Determine which EventGroup to delete.
2. Call Delete: Use DeleteEventGroup.
3. Confirm Deletion: The EventGroup will be in DELETED state.
4. Note: Deletion is permanent and cannot be reversed.

​

Listing and Filtering

1. Basic Listing: Call ListEventGroups with just a parent to get all EventGroups.
2. Filter by Consumer: Use filter.measurement_consumer_in to find EventGroups for specific consumers.
3. Filter by Date: Use data availability filters to find EventGroups for specific time periods.
4. Search Metadata: Use filter.metadata_search_query to search within metadata.
5. Include Deleted: Set show_deleted = true to include deleted EventGroups.
6. Order Results: Use order_by to sort by data availability start time.

​

Best Practices

​

Data Availability Intervals

• Start Time: Always required. Set to when the first event occurred.
• End Time: Optional. Omit for ongoing campaigns (unbounded interval).
• Accuracy: Only specify intervals where you actually have event data.
• Updates: Update the interval as campaigns progress or end.

​

Metadata Management

• Completeness: Provide comprehensive metadata to enable accurate filtering and search.
• Consistency: Use consistent naming and formatting across EventGroups.
• Updates: Keep metadata current as campaign details change.
• Privacy: Ensure metadata doesn’t contain sensitive information.

​

Batch Operations

• Efficiency: Use batch operations when creating or updating multiple EventGroups.
• Limits: Respect the 50 EventGroup limit per batch.
• Error Handling: If any operation fails, the entire batch fails.
• Atomicity: All operations in a batch succeed or all fail together.

​

State Management

• Active State: Normal operational state for EventGroups.
• Deletion: Only delete EventGroups when they should never be used again.
• Immutability: Some fields like measurement_consumer cannot be changed after creation.
• Views: Use appropriate views (BASIC vs WITH_ACTIVITY_SUMMARY) based on your needs.