Google Analytics 4 integration

What you can sync

E-commerce events: Complete purchase funnel tracking with item details
Standard events: User engagement, navigation, and content interaction
Custom events: Any business-specific events you want to track
Audiences: Send audience membership as custom events

Prerequisites

A Google Analytics 4 property
A Measurement ID (format: G-XXXXXXXXXX)
A Measurement Protocol API Secret

You can find your Measurement ID in Google Analytics under Admin → Data Streams → [Your Stream] → Measurement ID. Create an API Secret under Admin → Data Streams → [Your Stream] → Measurement Protocol API secrets.

Event types

Google Analytics 4 supports three types of events that Masivo automatically handles:

E-commerce events (12 events)

These events track the complete purchase journey and preserve the items array structure:

Event	When to send	Key parameters
`add_payment_info`	User adds payment information	`items`, `currency`, `value`, `payment_type`
`add_shipping_info`	User adds shipping information	`items`, `currency`, `value`, `shipping_tier`
`add_to_cart`	User adds item to cart	`items`, `currency`, `value`
`add_to_wishlist`	User adds item to wishlist	`items`, `currency`, `value`
`begin_checkout`	User starts checkout process	`items`, `currency`, `value`, `coupon`
`purchase`	User completes purchase	`items`, `transaction_id`, `currency`, `value`, `tax`, `shipping`
`refund`	Purchase is refunded	`items`, `transaction_id`, `currency`, `value`
`remove_from_cart`	User removes item from cart	`items`, `currency`, `value`
`select_item`	User selects a product	`items`, `item_list_id`, `item_list_name`
`view_cart`	User views their cart	`items`, `currency`, `value`
`view_item`	User views product details	`items`, `currency`, `value`
`view_item_list`	User views a list of products	`items`, `item_list_id`, `item_list_name`

Standard events (20 events)

These events track user engagement and interaction:

Event	When to send	Key parameters
`app_open`	App is opened	-
`click`	User clicks outbound link	`link_url`, `link_text`, `link_domain`
`file_download`	User downloads a file	`file_name`, `file_extension`, `link_url`
`generate_lead`	User submits a form	`currency`, `value`
`login`	User logs in	`method`
`page_view`	Page loads (web)	`page_location`, `page_title`, `page_referrer`
`screen_view`	Screen loads (app)	`screen_name`, `screen_class`
`scroll`	User scrolls 90% of page	`percent_scrolled`
`search`	User performs a search	`search_term`
`select_content`	User selects content	`content_type`, `item_id`
`select_promotion`	User clicks promotion	`promotion_id`, `promotion_name`, `creative_name`
`share`	User shares content	`method`, `content_type`, `item_id`
`sign_up`	User creates account	`method`
`tutorial_begin`	User starts tutorial	-
`tutorial_complete`	User completes tutorial	-
`video_complete`	User completes video	`video_title`, `video_url`, `video_duration`
`video_progress`	Video reaches milestone	`video_title`, `video_url`, `video_percent`
`video_start`	User starts video	`video_title`, `video_url`, `video_provider`
`view_promotion`	User sees promotion	`promotion_id`, `promotion_name`, `creative_name`
`view_search_results`	User views search results	`search_term`

Custom events

Any event not matching GA4 standard events will be sent as a custom event with flattened parameters.

Configuration

Go to Settings → Integrations → Google Analytics 4 in the Masivo dashboard
Enter your Measurement ID (format: G-XXXXXXXXXX)
Enter your API Secret
Enable the features you want to sync:
- Events: All standard GA4 events
- Purchases: Only fulfilled purchases
- Audiences: Calculate and Delete operations

Make sure your Measurement ID starts with “G-” (for GA4). Universal Analytics properties (starting with “UA-”) are not supported.

How it works

Once configured, Masivo automatically transforms and sends your data to Google Analytics 4:

Real-time sync: Events are sent as they occur in Masivo
Smart transformation: Events are automatically transformed to match GA4’s expected format
Event type detection: Masivo detects if an event is e-commerce, standard, or custom
Data validation: Configuration and data are validated before sending
Error handling: Failed syncs are logged for debugging

Automatic transformations

Masivo automatically handles several transformations to ensure compatibility:

Event names: Converted to lowercase (e.g., PURCHASE → purchase)
Field mapping: Common alternative field names are mapped automatically
Items preservation: E-commerce events preserve the full items array structure
Parameter flattening: Custom events flatten nested objects into flat key-value pairs
Timestamp conversion: Converts timestamps to GA4’s microsecond format

Data structure

Event format

Send events to Masivo using this structure:

{
  "type": "PURCHASE",
  "customer_id": "cust_123",
  "transaction_id": "ORD-789",
  "currency": "USD",
  "value": 159.99,
  "tax": 12.0,
  "shipping": 8.0,
  "order": {
    "purchase_id": "abc123",
    "value": 300,
    "discounted_value": 300,
    "products": [
      {
        "sku": "dawd",
        "amount": 1,
        "value": 12
      }
    ],
    "payment_method": "CREDIT"
  },
  "items": [
    {
      "item_id": "SKU-001",
      "item_name": "Running Shoes",
      "item_brand": "Nike",
      "item_category": "Footwear",
      "price": 129.99,
      "quantity": 1
    }
  ]
}

Items array structure

For e-commerce events, each item in the items array supports these native GA4 fields:

{
  "item_id": "SKU-001", // Required: Product ID
  "item_name": "Running Shoes", // Required: Product name
  "item_brand": "Nike", // Brand
  "item_category": "Footwear", // Primary category
  "item_category2": "Athletic", // Secondary category
  "item_category3": "Running", // Tertiary category
  "item_category4": "", // Fourth-level category
  "item_category5": "", // Fifth-level category
  "item_variant": "Blue/Size 10", // Variant (size, color, etc.)
  "price": 129.99, // Unit price
  "quantity": 1, // Quantity
  "currency": "USD", // Currency code
  "discount": 10.0, // Discount amount
  "coupon": "SAVE10", // Coupon code
  "affiliation": "Online Store", // Store/affiliate name
  "item_list_id": "search_results", // List identifier
  "item_list_name": "Search Results", // List name
  "location_id": "STORE-001", // Physical location ID
  "index": 0, // Position in list
  "promotion_id": "PROMO-123", // Promotion identifier
  "promotion_name": "Summer Sale", // Promotion name
  "creative_name": "Hero Banner", // Creative/banner name
  "creative_slot": "homepage_top" // Creative position
}

At minimum, each item must have either item_id or item_name. All other fields are optional but recommended for better reporting.

Field mapping

Masivo automatically maps common alternative field names to GA4 standards:

Your field	Maps to GA4	Context
`customer_id`	`client_id`	Event level
`id`	`item_id`	In items
`name`	`item_name`	In items
`brand`	`item_brand`	In items
`unit_price`	`price`	In items
`order_id`	`transaction_id`	In purchase/refund
`query`	`search_term`	In search events

Most GA4 standard fields (like currency, value, tax, shipping, method, screen_name, etc.) do NOT need transformation. Only the fields listed above are automatically mapped from alternative names.

Examples

Add to cart event

{
  "type": "add_to_cart",
  "customer_id": "cust_123",
  "currency": "USD",
  "value": 49.99,
  "items": [
    {
      "item_id": "PROD-456",
      "item_name": "Wireless Headphones",
      "item_brand": "Sony",
      "item_category": "Electronics",
      "price": 49.99,
      "quantity": 1,
      "item_list_name": "Search Results"
    }
  ]
}

Search event

{
  "type": "search",
  "customer_id": "cust_123",
  "search_term": "wireless headphones"
}

Audience synchronization

Audience calculation operations

When audiences are calculated in Masivo, they’re sent to Google Analytics 4 as custom events:

Event name: audience_updated
Includes: audience_id, audience_name, customers_count, action
Customer IDs are included for reference

Audience DELETE operations

When audiences are deleted:

Event name: audience_removed
Automatically includes all customers in the audience
Ensures proper cleanup in your GA4 reports

Audience events use a special client_id of “audience_manager” and include all relevant customer information for proper tracking.

Validation

Before sending data to Google Analytics 4, Masivo validates:

API credentials: Measurement ID and API Secret are configured
Event configuration: The event type is enabled in your settings
Data completeness: Required fields are present for each event type
Purchase status: Only fulfilled purchases are sent (if configured)

Best practices

Always include customer_id: Required for user identification (automatically mapped to GA4’s client_id)
Use consistent item IDs: Ensures accurate product analytics
Include all item fields: Richer data enables better reporting
Add currency codes: Required for accurate revenue tracking
Send timestamps: Use issued_at for accurate event timing
Include promotional data: Track campaign effectiveness with promotion_id, promotion_name, etc.
Use item_list_name: Helps track where users interact with products

Limitations

Items array: Only preserved for e-commerce events; custom events flatten arrays
Nested objects: Custom events flatten nested objects into prefix_key format
Data types: Only primitives (string, number, boolean) are supported in custom events
Rate limits: Subject to Google Analytics 4 rate limits (typically not an issue)

Custom events (non-GA4 standard) will have their parameters flattened. For example, nested objects become event_object_field format.

Troubleshooting

Events not appearing in GA4

Check that your Measurement ID starts with “G-” (not “UA-”)
Verify your API Secret is correct
Ensure the event type is enabled in Masivo settings
Check that customer_id is included in your events

Purchase events missing

Verify that “Purchases” is enabled in settings
Confirm purchases are marked as fulfilled
Check that transaction_id is unique for each purchase
Ensure items array contains at least one item with item_id or item_name

Items not showing in reports

Verify each item has item_id or item_name
Check that currency and price are included
Ensure numeric fields (price, quantity) are sent as numbers, not strings

GA4 can take up to 24-48 hours to process and display new events in reports. Use the DebugView feature in GA4 to see events in real-time during testing.

Debug mode

To test your integration before going live:

Enable debug mode in your GA4 property
Send test events through Masivo
View real-time events in GA4’s DebugView
Verify event structure and parameters

Use GA4’s DebugView (Admin → DebugView) to see events in real-time and verify the data structure before sending production traffic.

Get Started

Guides

Use cases

Integrations

Google Analytics 4 integration

What you can sync

Prerequisites

Event types

E-commerce events (12 events)

Standard events (20 events)

Custom events

Configuration

How it works

Automatic transformations

Data structure

Event format

Items array structure

Field mapping

Examples

Add to cart event

Search event

Audience synchronization

Audience calculation operations

Audience DELETE operations

Validation

Best practices

Limitations

Troubleshooting

Events not appearing in GA4

Purchase events missing

Items not showing in reports

Debug mode

​What you can sync

​Prerequisites

​Event types

​E-commerce events (12 events)

​Standard events (20 events)

​Custom events

​Configuration

​How it works

​Automatic transformations

​Data structure

​Event format

​Items array structure

​Field mapping

​Examples

​Add to cart event

​Search event

​Audience synchronization

​Audience calculation operations

​Audience DELETE operations

​Validation

​Best practices

​Limitations

​Troubleshooting

​Events not appearing in GA4

​Purchase events missing

​Items not showing in reports

​Debug mode

What you can sync

Prerequisites

Event types

E-commerce events (12 events)

Standard events (20 events)

Custom events

Configuration

How it works

Automatic transformations

Data structure

Event format

Items array structure

Field mapping

Examples

Add to cart event

Search event

Audience synchronization

Audience calculation operations

Audience DELETE operations

Validation

Best practices

Limitations

Troubleshooting

Events not appearing in GA4

Purchase events missing

Items not showing in reports

Debug mode