Google Analytics 4 integration

Sync Masivo customers, events, and audiences to Google Analytics 4

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

1. Go to Settings → Integrations → Google Analytics 4 in the Masivo dashboard
2. Enter your Measurement ID (format: G-XXXXXXXXXX)
3. Enter your API Secret
4. 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:

1. Real-time sync: Events are sent as they occur in Masivo
2. Smart transformation: Events are automatically transformed to match GA4’s expected format
3. Event type detection: Masivo detects if an event is e-commerce, standard, or custom
4. Data validation: Configuration and data are validated before sending
5. 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

1. Always include customer_id: Required for user identification (automatically mapped to GA4’s client_id)
2. Use consistent item IDs: Ensures accurate product analytics
3. Include all item fields: Richer data enables better reporting
4. Add currency codes: Required for accurate revenue tracking
5. Send timestamps: Use issued_at for accurate event timing
6. Include promotional data: Track campaign effectiveness with promotion_id, promotion_name, etc.
7. 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:

1. Enable debug mode in your GA4 property
2. Send test events through Masivo
3. View real-time events in GA4’s DebugView
4. 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.