> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Info>
  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**.
</Info>

## 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

<Warning>
  Make sure your Measurement ID starts with "G-" (for GA4). Universal Analytics
  properties (starting with "UA-") are not supported.
</Warning>

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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
}
```

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

## 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   |

<Info>
  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.
</Info>

## Examples

### Add to cart event

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<Note>
  Audience events use a special `client_id` of "audience\_manager" and include
  all relevant customer information for proper tracking.
</Note>

## 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)

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

## 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

<Info>
  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.
</Info>

## 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

<Tip>
  Use GA4's DebugView (**Admin → DebugView**) to see events in real-time and
  verify the data structure before sending production traffic.
</Tip>