> For the complete documentation index, see [llms.txt](https://learn.cozmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.cozmos.com/guides/analytics/tracking-custom-sphere-events-with-gtm.md).

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