# Tracking Custom Sphere Events with GTM

In order to capture interaction data from our 3D object canvas in a clear and understandable way within your GTM analytics there is a need to setup custom Sphere events. The following guide will walk you through the configuration required.

### Creating Variables

You will need to create three new variables to track and properly display the parameters from your custom events.

* Open your Admin Workspace and in the left hand menu select Variables
* Scroll down to the block labelled 'User Defined Variables' and click the <mark style="color:yellow;">New</mark> button to add
* Select <mark style="color:yellow;">Data Layer Variable</mark> as the type and use the pen icon to edit the variable configuration

<figure><img src="/files/LVcfLxRDoq5wwXh0R9rN" alt=""><figcaption></figcaption></figure>

* Add the Data Layer Variable name in the space provided. You will need to create Three individual Variables. These must be called:
  * <mark style="color:yellow;">`eventAction`</mark>
  * <mark style="color:yellow;">`eventName`</mark>
  * <mark style="color:yellow;">`eventCategory`</mark>

<figure><img src="/files/MjUYdEwwB8zrfaNHCm99" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Variable naming must be exactly as shown above.
{% endhint %}

* When saving each variable name you can use the same name but just add a space between the words. Example: Variable <mark style="color:yellow;">`eventAction`</mark> saved as <mark style="color:yellow;">Event Action</mark>

Once you have created and saved your variables you need to create a trigger for the event.

### Creating an Event Trigger in GTM

The trigger will let GTM know when the new event should fire.&#x20;

* Open your GTM Workspace and select Tags in the left menu
* Select New in the top right corner

<figure><img src="/files/7aZXQywtU3KNFTEZQ4w6" alt=""><figcaption></figcaption></figure>

In the pop up which appears select your existing GA4 Configuration tag and enter the following details:

* Event Name: <mark style="color:yellow;">`sphere_event`</mark>
* Add Event Paramaters: <mark style="color:yellow;">`eventAction`</mark> , <mark style="color:yellow;">`eventName`</mark> , <mark style="color:yellow;">`eventCategory`</mark>
* The Event Parameter area is free text input, not a selector so be sure to check format and spelling. Your table should look like the below image once complete.

<figure><img src="/files/pJeIVdswG3O8UfpUiYOX" alt=""><figcaption></figcaption></figure>

### Adding and attaching Triggers to Tags

* Open your GTM Workspace and select Triggers in the left menu
* Select New in the top right corner

<figure><img src="/files/n0L1lLkz5HEw7VmLQLxz" alt=""><figcaption></figcaption></figure>

* Select Custom Event as the new trigger type.
* The Event name must be: <mark style="color:yellow;">`sphere_event`</mark>

<figure><img src="/files/Gn2mZzEMxGFUmqpJnIVz" alt=""><figcaption></figcaption></figure>

If everything has been configured correctly, your Tag Configuration will look like the below screenshot:

<figure><img src="/files/oW3JmeOkMPDzZDc6bbKP" alt=""><figcaption></figcaption></figure>

The final step is to Submit these changes

### Google Analytics Configuration

All custom parameters must be added as Custom Definitions in GA4 if you want to see/use them in places like Funnel reports, Exploration, see their reporting cards in standard reports, etc.

{% hint style="info" %}
GA4 takes up to 24 hours to process the data and configurations, so the changes you have made will not appear immediately in reports.
{% endhint %}

To set this up, open you Analytics dashboard, go to Admin and select <mark style="color:yellow;">Custom Definitions</mark>

<figure><img src="/files/G5iZ5TvOvYfwRqBKwuvJ" alt=""><figcaption></figcaption></figure>

Click on the Create Custom Definitions option and then enter the following:

* Name of the parameter: GA4 will display this in your reports
* Scope: As we are applying this parameter to only one event and not all user events we need to select the scope as <mark style="color:yellow;">Event</mark>
* Event parameter: This my match exactly the name used in your GTM tag. ( <mark style="color:yellow;">`eventAction, eventName,eventCategory`</mark>)
* You will need to create a new dimension for each parameter, so in total you will create 3.

<figure><img src="/files/IjvT8tnaHo4lAdXUU1Vx" alt=""><figcaption></figcaption></figure>

### Configure and Create Custom Events in Google Analytics

GA4 has a feature called “Create event”. It allows you to create events based on other events already tracked by GA4. For example, if you track `page_view` events and you want to create a separate event just for the “Thank you” page, you can use this feature to create a *`thankyou_page_visit`* event.

* Go to your Admin page, click <mark style="color:yellow;">Create Event</mark>, then click <mark style="color:yellow;">Create</mark>

<figure><img src="/files/myTuTeZfbR7OtcXmlaqq" alt=""><figcaption></figcaption></figure>

* Enter the name for your custom event, for consistency we suggest calling this <mark style="color:yellow;">`sphere_event`</mark>
* Keep the checkbox <mark style="color:yellow;">`'Copy parameters from the source event'`</mark> enabled.

<figure><img src="/files/M7L4Bv6ybgMSc6bU17fp" alt=""><figcaption></figcaption></figure>

After successful configuration the data will be available in Google Analytics 4 panel. Keep in mind that Google is constantly updating Google Analytics 4. So if something looks different, don’t worry. Keep browsing the interface, and you will eventually find what you need.

{% hint style="info" %}
If you can’t see the *Sphere Action, Sphere Event Category, Sphere Event Name* (or whatever custom parameters you are looking for), you must register the custom reports in *All Events* > *Manage Custom Definitions*. Then wait up to 24 hours until the data appears in the reports.
{% endhint %}

It's important to know that Google has certain limitations on custom events, these are:

* You can send up to 25 event parameters together with the event. Based on various experiments, automatically collected parameters (like *page\_location*, etc.) are counted in this limit.
* The maximum length of the parameter name is 40 characters.
* The maximum length of the value (of a parameter) is 100 characters.

For a full list of limitations, please visit [Google's support page.](https://support.google.com/analytics/answer/9267744)

Please feel free to get in touch with [Cozmos Support](/help/support.md) if you encounter any issues when setting up Custom events for your spheres.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cozmos.com/guides/analytics/tracking-custom-sphere-events-with-gtm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.