Send events from server-side Google Tag Manager

If your website sends Google Analytics 4 (GA4) events to a server-side Google Tag Manager container, the same container can forward each event to Amperity. The Amperity Real Time Events Tag is a server tag template, published in the gtm-server-amperity-real-time repository on GitHub. It sends every event your server container receives to an Amperity event stream, where the events keep your real-time profiles current. Nothing changes on your website: the tag runs in your server container, and your Amperity credentials never reach the browser.

How the tag works

Your website’s GA4 tag sends events to your server container. The container’s GA4 client turns each request into event data, and the Amperity Real Time Events Tag sends that event data to your event stream with POST /prof/events/{stream-id} in the Real-time API.

The tag shapes each event before it sends it:

  • Every field is forwarded. The tag reads all of the event data the client produced, not a fixed list of fields. This includes fields such as ip_override and user_agent when the client provides them. See Leave fields out.

  • Two fields are renamed. client_id is sent as visitor_id, and page_location is sent as page_url.

  • Nested values are flattened. Objects and arrays become dot-separated property names, and each array item gets its own numbered properties. For example, the item_id of the first item in a GA4 items array is sent as items.0.item_id, and the second item’s as items.1.item_id.

  • Every event has a name. An event without an event_name is sent with event_name set to unknown.

  • Three properties identify the source. amp_adapter is always gtm-server-container, and amp_container_id and amp_container_version identify the server container and its published version.

  • No event timestamp is added. Amperity timestamps each event when it receives it. See Prepare the event stream.

Before you begin

This integration needs:

  • A server-side Google Tag Manager container with a tagging server, and a GA4 tag on your website that sends events to it. See Google’s server-side tagging documentation to set one up.

  • An event stream for the GA4 events. See Prepare the event stream.

  • A profile collection that subscribes to the event stream, so that the events update profiles. See Real-time profiles.

  • An access token from an API key with the profile-events:write or streaming-ingest-api:write permission. An API key with only the Streaming Ingest Write Access policy can send events and nothing else. See Generate access token.

  • Your tenant ID. See Find your tenant ID.

Prepare the event stream

Configure the event stream for the events GA4 sends:

  • Recognize events by event_name. GA4 names every event in its event_name property, such as page_view, add_to_cart, or purchase. Set the stream’s Recognition method to read event_name, and add an event type for each event name you want to process. An event whose name has no event type is ignored.

  • Use the received time. The tag sends no event timestamp. In each event type, keep Use received at time selected on the event_timestamp field, so that each event is timestamped with the time Amperity receives it. A timestamp path that matches nothing in the event marks the event invalid.

  • Use the flattened property names. When you define an event type’s fields, read the properties as the tag sends them, such as visitor_id, page_url, and items.0.item_id. A name that contains a period must be wrapped in backticks in an expression, or Amperity reads it as a nested path and finds no value:

    `items.0.item_id`
    

    Adding fields from the stream’s sample events uses the exact names and adds the backticks for you. See Configure an event type from a sample.

  • Assign a Keychain key. Assign a Keychain key to at least one property that identifies a customer, so that Amperity can match the event to a profile. visitor_id identifies a browser rather than a person. If your GA4 tag sets a user ID, the event carries it as user_id. See Identity recognition.

  • Process events. Set the Event stream mode to Process.

Copy the HTTP ENDPOINT from the stream’s endpoint configuration. The tag needs both of its parts: the base URL before /prof/events/, and the stream ID after it, which starts with esm-.

Add the template to your container

To add the Amperity Real Time Events Tag to your server container

Step 1.

Download template.tpl from the repository with the Download raw file button on that page.

Step 2.

In Google Tag Manager, open your server container, and then select Templates.

Step 3.

Under Tag Templates, click New.

Step 4.

In the Template Editor, open the More actions menu, choose Import, and then select template.tpl.

Step 5.

Review the template’s Permissions tab, and then click Save. The template appears under Tag Templates as Amperity Real Time Events Tag.

The template requests these permissions:

Permission

Scope

Sends HTTP requests

https://*.amperity.com/prof/events/* only.

Reads event data

All event data, because the tag forwards every field.

Reads container data

The container ID and version, which the tag sends as amp_container_id and amp_container_version.

Logs to console

In debug mode only.

Configure the tag

To configure the tag

Step 1.

In your server container, select Tags, click New, and then select Amperity Real Time Events Tag as the tag type.

Step 2.

Fill in the tag’s settings:

Setting

Value

Amperity API Base URL

The part of the stream’s HTTP ENDPOINT before /prof/events/, without a trailing slash, such as https://app.amperity.com. The setting defaults to https://app.amperity.com; replace it if your endpoint uses a different host. The tag sends events only to hosts in the amperity.com domain.

Amperity Tenant ID

Your tenant ID.

Amperity Event Stream ID

The part of the stream’s HTTP ENDPOINT after /prof/events/, which starts with esm-.

Amperity API Key (JWT)

The access token.

Enable debug logging

Logs each event name and response status to the console. Logging runs only in preview and debug mode, never in the published container.

Step 3.

Under Triggering, add a trigger of type Custom that fires on the events from your GA4 client. For example, fire on Some events where Client Name equals the name of your GA4 client.

Step 4.

Click Save.

The access token is stored in the tag’s settings. It is never sent to the browser, but anyone with edit access to the container can read it. Use an API key with only the Streaming Ingest Write Access policy, and revoke its tokens if the container’s access changes.

If the access token was generated with an expiration, Amperity rejects the tag’s requests once it expires. Generate a new token and update the tag before then.

Leave fields out

The tag forwards every field the GA4 client provides. When the client provides them, these include the visitor’s IP address in ip_override and their browser in user_agent.

To keep fields from reaching Amperity, add a transformation to your server container that excludes them. Limit the transformation to the Amperity Real Time Events Tag, so that your other tags still receive the fields. See Google’s transformations documentation .

Test and publish

To test the tag and publish the container

Step 1.

In your server container, click Preview, and then browse your website so that it sends GA4 events.

Step 2.

Select an event in the preview, and confirm that the Amperity Real Time Events Tag fired and succeeded. The tag succeeds when Amperity responds with a 2xx status, such as 202 Accepted, and fails for any other response.

Step 3.

In Amperity, open the event stream’s Explorer tab and confirm that sample events arrive and are valid.

Step 4.

In Google Tag Manager, submit and publish the server container.

Troubleshoot the tag

Symptom

Cause and fix

The tag fails, and the console reports that a send_http permission was denied.

The Amperity API Base URL isn’t an amperity.com host. Correct the base URL.

The tag fails with 401 Unauthorized.

The access token is missing, invalid, or expired, or the tenant ID is missing. Generate a new token, and check the Amperity Tenant ID setting.

The tag fails with 403 Forbidden.

The API key lacks the profile-events:write or streaming-ingest-api:write permission, or the token belongs to a different tenant than the Amperity Tenant ID setting names. Check the API key’s permissions and the tenant ID.

The tag fails with another status.

See The sender receives an error.

The tag succeeds, but no events appear in the stream.

The stream’s Event stream mode is Drop. Amperity answers 204 No Content, which the tag reports as a success, and discards the event. Set the mode to Process.

The tag succeeds, but the stream’s events are unrecognized.

The stream’s Recognition method doesn’t read event_name. See Prepare the event stream.

The tag succeeds, but the stream’s events are ignored.

The stream has no event type for the event’s name. Add an event type for it. See Events are unrecognized, ignored, or invalid.

For profiles that don’t update after events arrive, see Troubleshoot real-time.