​
Google Analytics 4 (GA4) Measurement Protocol Integration

​
Overview

This guide explains how to send your Hardal analytics data directly to Google Analytics 4 (GA4) using the Measurement Protocol. This server-to-server integration enables you to maintain accurate analytics when client-side tracking is limited by ad blockers or privacy controls.

​
Prerequisites

Before setting up this integration, ensure you have:

  • An active Hardal account with the tracking script installed

  • Access to your Google Analytics 4 property

  • A GA4 data stream created for your website or app

  • API secret and Measurement ID from your GA4 property

  • Basic understanding of HTTP requests and JSON

​
Setting Up GA4 Measurement Protocol

​
Obtain your GA4 API credentials

1

Sign in to Google Analytics

Access your Google Analytics 4 property at analytics.google.com

2

Navigate to Data Streams

Go to Admin > Data Streams and select your web data stream

3

Access API secrets

Click on Measurement Protocol API secrets in the stream settings

4

Create a new secret

Click the Create button to generate a new API secret

5

Copy credentials

Copy both your Measurement ID (G-XXXXXXXX) and the newly created API Secret

​
Configuring the Hardal Integration

​
Access Hardal destinations

1

Log in to Hardal

Sign in to your Hardal dashboard at app.usehardal.com

2

Access Marketing Destinations

Navigate to the Marketing Destinations section in the main menu

3

Add new destination

Click the Add Custom Destination button

4

Select GA4 template

From the available templates, select “GA4 Measurement Protocol” (or create a custom API connection if not available)

​
Endpoint Configuration

Configure your GA4 endpoint with the following settings:

{
  "endpoint_label": "Google Analytics 4",
  "endpoint_id": "ga4-measurement-protocol",
  "endpoint_url": "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_API_SECRET",
  "request_method": "POST",
  "content_type": "application/json",
  "request_format": {
    "client_id": "##user_id##",
    "events": [
      {
        "name": "##event_name##",
        "params": {
          "session_id": "##session_id##",
          "engagement_time_msec": 100,
          "page_location": "##page.url##",
          "page_title": "##page.title##",
          "page_referrer": "##page.referrer##"
        }
      }
    ]
  }
}

​
Event Mapping

​
Basic Event Mapping

The integration automatically maps common Hardal events to GA4 events. Here’s how key events are mapped:

Hardal EventGA4 Event
page_viewpage_view
clickclick
purchasepurchase
add_to_cartadd_to_cart
begin_checkoutbegin_checkout
view_itemview_item

​
Custom Event Mapping

For custom events, you may need to create a specialized mapping. Here’s an example mapping for an e-commerce purchase event:

{
  "endpoint_label": "GA4 E-commerce",
  "endpoint_id": "ga4-ecommerce",
  "endpoint_url": "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_API_SECRET",
  "request_method": "POST",
  "content_type": "application/json",
  "request_format": {
    "client_id": "##user_id##",
    "events": [
      {
        "name": "purchase",
        "params": {
          "transaction_id": "##properties.transaction_id##",
          "value": ##properties.value##,
          "currency": "##properties.currency##",
          "tax": ##properties.tax##,
          "shipping": ##properties.shipping##,
          "items": ##properties.items##,
          "session_id": "##session_id##",
          "engagement_time_msec": 100
        }
      }
    ]
  }
}

​
Advanced Configuration

​
Including User Properties

To include user properties with your events, add a user_properties object to your request format:

{
  "client_id": "##user_id##",
  "user_properties": {
    "user_type": {
      "value": "##properties.user_type##"
    },
    "membership_level": {
      "value": "##properties.membership_level##"
    }
  },
  "events": [
    // Event data here
  ]
}

​
Setting Custom Parameters

For advanced use cases, you can include custom parameters with your events:

{
  "name": "##event_name##",
  "params": {
    "custom_param1": "##properties.custom_param1##",
    "custom_param2": "##properties.custom_param2##",
    "session_id": "##session_id##",
    "engagement_time_msec": 100
  }
}

​
Event Validation

After setting up your integration, verify that events are being properly received:

  1. Send test events through Hardal

  2. Check the GA4 DebugView to see if events are appearing

  3. Verify events are showing in GA4 reports (may take up to 24 hours)

​
Best Practices

​
Performance Considerations

  • Batch multiple events in a single request when possible (up to 25 events)

  • Implement error handling and retry logic for failed requests

  • Use appropriate caching strategies to handle high traffic volumes

​
Data Quality

  • Include session_id and engagement_time_msec with all events

  • Use consistent parameter naming conventions

  • Avoid sending Personally Identifiable Information (PII)

  • Validate data formats before sending (especially for currency values)

​
Privacy Compliance

  • Ensure your data collection complies with privacy regulations

  • Honor user consent preferences when applicable

  • Include appropriate disclosures in your privacy policy

  • Consider implementing data filtering for sensitive information

​
Troubleshooting

​
Complete Implementation Example

Here’s a complete implementation example showing how to set up a custom destination in Hardal that sends e-commerce purchase events to GA4:

{
  "endpoint_label": "GA4 E-commerce Complete",
  "endpoint_id": "ga4-ecommerce-full",
  "endpoint_url": "https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXX&api_secret=YOUR_API_SECRET",
  "request_method": "POST",
  "content_type": "application/json",
  "request_format": {
    "client_id": "##user_id##",
    "user_id": "##properties.customer_id##",
    "non_personalized_ads": false,
    "events": [
      {
        "name": "purchase",
        "params": {
          "transaction_id": "##properties.order_id##",
          "value": ##properties.total##,
          "currency": "##properties.currency##",
          "tax": ##properties.tax##,
          "shipping": ##properties.shipping##,
          "coupon": "##properties.coupon##",
          "items": [
            {
              "item_id": "##properties.items[0].item_id##",
              "item_name": "##properties.items[0].item_name##",
              "price": ##properties.items[0].price##,
              "quantity": ##properties.items[0].quantity##,
              "item_category": "##properties.items[0].category##"
            }
          ],
          "session_id": "##session_id##",
          "engagement_time_msec": 100,
          "page_location": "##page.url##",
          "page_title": "##page.title##"
        }
      }
    ]
  },
  "headers": {
    "Content-Type": "application/json"
  }
}

​
Limitations

Be aware of these GA4 Measurement Protocol limitations:

  • Maximum 25 events per request

  • Maximum 25 parameters per event

  • Maximum 25 user properties per request

  • User property names limited to 24 characters

  • User property values limited to 36 characters

  • Event names limited to 40 characters

  • Parameter names limited to 40 characters

  • Parameter values limited to 100 characters (500 for GA4 360)

  • Maximum request body size of 130KB

Was this page helpful?

Previous
Google Ads Conversions
Next