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_overrideanduser_agentwhen the client provides them. See Leave fields out.Two fields are renamed.
client_idis sent asvisitor_id, andpage_locationis sent aspage_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_idof the first item in a GA4itemsarray is sent asitems.0.item_id, and the second item’s asitems.1.item_id.Every event has a name. An event without an
event_nameis sent withevent_nameset tounknown.Three properties identify the source.
amp_adapteris alwaysgtm-server-container, andamp_container_idandamp_container_versionidentify 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 itsevent_nameproperty, such aspage_view,add_to_cart, orpurchase. Set the stream’s Recognition method to readevent_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_timestampfield, 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, anditems.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_ididentifies a browser rather than a person. If your GA4 tag sets a user ID, the event carries it asuser_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
|
Download template.tpl from the repository with the Download raw file button on that page. |
|
In Google Tag Manager, open your server container, and then select Templates. |
|
Under Tag Templates, click New. |
|
In the Template Editor, open the More actions menu, choose Import, and then select |
|
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 |
|
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 |
Logs to console |
In debug mode only. |
Configure the tag¶
To configure the tag
|
In your server container, select Tags, click New, and then select Amperity Real Time Events Tag as the tag type. |
||||||||||||
|
Fill in the tag’s settings:
|
||||||||||||
|
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. |
||||||||||||
|
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
|
In your server container, click Preview, and then browse your website so that it sends GA4 events. |
|
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 |
|
In Amperity, open the event stream’s Explorer tab and confirm that sample events arrive and are valid. |
|
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 |
The Amperity API Base URL isn’t an |
The tag fails with |
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 |
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. |
|
The tag succeeds, but no events appear in the stream. |
The stream’s Event stream mode is Drop. Amperity answers |
The tag succeeds, but the stream’s events are unrecognized. |
The stream’s Recognition method doesn’t read |
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.