# Google Analytics Utils

*Category:* Utilities
*Section:* Helper
*Source:* https://uikit.developers.rio.cloud/#/utilities/getTrackingAttributes
*Captured:* 2026-04-27T14:59:29.682Z

Utility helpers for Google Analytics integration, including attribute generation and push helpers.

## Google Analytics Utils

Use these helpers to create consistent tracking attributes, push events intowindow.dataLayer, and wrap business logic with tracking in one call.

> Important: getTrackingAttributes is the preferred and required way to add GA tracking attributes to UI elements in this project. AnalyticsAnalysisOverlay only works when elements use thedata-track-ga-event-* attributes.

## Available helpers

NameExampleDescriptiongetTrackingAttributes(...)getTrackingAttributes({ trigger: 'click', category: 'demo' })Creates the data-track-ga-event-* attributes for declarative tracking on DOM elements. This is the preferred approach for UI elements.gaPush(...)gaPush({ category: 'demo', action: 'click', label: 'cta' })Pushes an event into window.dataLayer programmatically. Use this when tracking should happen from imperative code, including hover interactions.executeAndTrack(...)executeAndTrack(myFn, { category: 'demo', action: 'run', label: 'myFn' })Wraps a function so it still runs normally and also sends a GA event afterward. Useful when you want tracking and business logic wired together in one call.

## Tracking attributesRecommended

Tracking attributes

> Recommended

**TRACKING_TRIGGER**

TRACKING_TRIGGER defines the allowed values for trigger ingetTrackingAttributes.

```typescript
type TRACKING_TRIGGER = 'click' | 'visibility';
```

type

TRACKING_TRIGGER

=

'click'

|

'visibility'

;

Hover is intentionally not part of TRACKING_TRIGGER. If you need to track hover interactions, send the event programmatically with gaPush or executeAndTrackfrom the relevant UI callback.

| Trigger | Use for |
| --- | --- |
| click | User actively clicks an element (buttons, links, controls). |
| visibility | Element becomes visible in the viewport. |

**TRACKING_ACTIONS and TRACKING_LABELS**

These exports are optional app-level maps that consuming applications can fill with shared action and label values. They are configuration points, not required runtime state.

```typescript
TRACKING_ACTIONS.dialogClose = 'dialog clicked';
TRACKING_LABELS.dialogClose = 'Dialog closed via close button';
```

TRACKING_ACTIONS

.

=

'dialog clicked'

;

TRACKING_LABELS

.

=

'Dialog closed via close button'

;

### Example: getTrackingAttributes()

getTrackingAttributes()
click visibility Disable value Tracked button {
"data-track-ga-event-trigger": "click",
"data-track-ga-event-category": "uikit demo",
"data-track-ga-event-action": "button click",
"data-track-ga-event-label": "utility_getTrackingAttributes_demo",
"data-track-ga-event-value": "1"
}

#### React (tsx)

```tsx
import { useMemo, useState } from 'react';

import Button from '@rio-cloud/rio-uikit/Button';
import { getTrackingAttributes, type TRACKING_TRIGGER } from '@rio-cloud/rio-uikit/googleAnalyticsUtils';

const triggerOptions: TRACKING_TRIGGER[] = ['click', 'visibility'];

const GoogleAnalyticsUtilsExample = () => {
    const [trigger, setTrigger] = useState<TRACKING_TRIGGER>('click');
    const [includeValue, setIncludeValue] = useState(true);

    const trackingAttributes = useMemo(
        () =>
            getTrackingAttributes({
                trigger,
                category: 'uikit demo',
                action: `button ${trigger}`,
                label: 'utility_getTrackingAttributes_demo',
                value: includeValue ? '1' : undefined,
            }),
        [includeValue, trigger]
    );

    return (
        <div className='bg-white border rounded padding-15'>
            <h4 className='margin-top-0'>getTrackingAttributes()</h4>
            <div className='display-flex gap-10 margin-bottom-15'>
                {triggerOptions.map(option => (
                    <Button
                        key={option}
                        bsSize='xs'
                        bsStyle='default'
                        className={option === trigger ? 'active' : ''}
                        onClick={() => setTrigger(option)}
                    >
                        {option}
                    </Button>
                ))}
                <Button bsSize='xs' bsStyle='default' onClick={() => setIncludeValue(previousValue => !previousValue)}>
                    {includeValue ? 'Disable value' : 'Enable value'}
                </Button>
            </div>

            <Button bsStyle='primary' {...trackingAttributes}>
                Tracked button
            </Button>

            <pre className='margin-top-15 bg-white border rounded padding-10 text-size-12'>
                {JSON.stringify(trackingAttributes, null, 2)}
            </pre>
        </div>
    );
};

export default GoogleAnalyticsUtilsExample;
```

#### HTML (html)

```html
<div class="bg-white border rounded padding-15">
    <h4 class="margin-top-0">getTrackingAttributes()</h4>
    <div class="display-flex gap-10 margin-bottom-15">
        <button type="button" class="btn btn-default btn-xs btn-component active" tabindex="0">click</button>
        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">visibility</button>
        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">Disable value</button>
    </div>
    <button type="button" data-track-ga-event-trigger="click" data-track-ga-event-category="uikit demo" data-track-ga-event-action="button click" data-track-ga-event-label="utility_getTrackingAttributes_demo" data-track-ga-event-value="1" class="btn btn-primary btn-component" tabindex="0">Tracked button</button>
    <pre class="margin-top-15 bg-white border rounded padding-10 text-size-12">{
  "data-track-ga-event-trigger": "click",
  "data-track-ga-event-category": "uikit demo",
  "data-track-ga-event-action": "button click",
  "data-track-ga-event-label": "utility_getTrackingAttributes_demo",
  "data-track-ga-event-value": "1"
}</pre>
</div>
```

## Imperative tracking

### Example: gaPush() and executeAndTrack()

gaPush() and executeAndTrack()
Use gaPush for direct imperative tracking, including hover interactions. Use executeAndTrack when the event should always be emitted together with a function call.
click visibility hover Disable value
Push event with gaPush executeAndTrack counter: 0 Clear dataLayer
[]

#### React (tsx)

```tsx
import { useMemo, useState } from 'react';

import Button from '@rio-cloud/rio-uikit/Button';
import { executeAndTrack, gaPush } from '@rio-cloud/rio-uikit/googleAnalyticsUtils';

type GaPushInteraction = 'click' | 'visibility' | 'hover';

const interactionOptions: GaPushInteraction[] = ['click', 'visibility', 'hover'];

const getDataLayer = () => {
    if (typeof window === 'undefined') {
        return [] as unknown[];
    }

    if (!Array.isArray(window.dataLayer)) {
        window.dataLayer = [];
    }

    return window.dataLayer;
};

const GoogleAnalyticsUtilsGaPushExample = () => {
    const [interaction, setInteraction] = useState<GaPushInteraction>('click');
    const [includeValue, setIncludeValue] = useState(true);
    const [dataLayerSnapshot, setDataLayerSnapshot] = useState<unknown[]>(() => [...getDataLayer()]);
    const [trackedCounter, setTrackedCounter] = useState(0);

    const refreshDataLayer = () => {
        setDataLayerSnapshot([...getDataLayer()]);
    };

    const trackedIncrement = useMemo(
        () =>
            executeAndTrack((value: number) => value + 1, {
                category: 'uikit demo',
                action: 'button click',
                label: 'utility_executeAndTrack_demo',
                value: 1,
            }),
        []
    );

    const handleGaPush = () => {
        gaPush({
            category: 'uikit demo',
            action: `manual ${interaction}`,
            label: 'utility_gaPush_demo',
            value: includeValue ? 1 : undefined,
        });

        refreshDataLayer();
    };

    const handleExecuteAndTrack = () => {
        const nextValue = trackedIncrement(trackedCounter);
        setTrackedCounter(nextValue);
        refreshDataLayer();
    };

    const handleClearDataLayer = () => {
        if (typeof window !== 'undefined') {
            window.dataLayer = [];
        }

        refreshDataLayer();
    };

    return (
        <div className='bg-white border rounded padding-15'>
            <h4 className='margin-top-0'>gaPush() and executeAndTrack()</h4>
            <p className='margin-bottom-15'>
                Use <code>gaPush</code> for direct imperative tracking, including hover interactions. Use
                <code>executeAndTrack</code> when the event should always be emitted together with a function call.
            </p>

            <div className='display-flex gap-10 margin-bottom-15'>
                {interactionOptions.map(option => (
                    <Button
                        key={option}
                        bsSize='xs'
                        bsStyle='default'
                        className={option === interaction ? 'active' : ''}
                        onClick={() => setInteraction(option)}
                    >
                        {option}
                    </Button>
                ))}
                <Button bsSize='xs' bsStyle='default' onClick={() => setIncludeValue(previousValue => !previousValue)}>
                    {includeValue ? 'Disable value' : 'Enable value'}
                </Button>
            </div>

            <div className='display-flex gap-10 margin-bottom-15'>
                <Button bsStyle='default' onClick={handleGaPush}>
                    Push event with gaPush
                </Button>
                <Button bsStyle='default' onClick={handleExecuteAndTrack}>
                    executeAndTrack counter: {trackedCounter}
                </Button>
                <Button bsStyle='muted' onClick={handleClearDataLayer}>
                    Clear dataLayer
                </Button>
            </div>

            <pre className='bg-white border rounded padding-10 margin-bottom-0 text-size-12'>
                {JSON.stringify(dataLayerSnapshot, null, 2)}
            </pre>
        </div>
    );
};

export default GoogleAnalyticsUtilsGaPushExample;
```

#### HTML (html)

```html
<div class="bg-white border rounded padding-15">
    <h4 class="margin-top-0">gaPush() and executeAndTrack()</h4>
    <p class="margin-bottom-15">Use <code>gaPush</code> for direct imperative tracking, including hover interactions. Use<code>executeAndTrack</code> when the event should always be emitted together with a function call.</p>
    <div class="display-flex gap-10 margin-bottom-15">
        <button type="button" class="btn btn-default btn-xs btn-component active" tabindex="0">click</button>
        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">visibility</button>
        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">hover</button>
        <button type="button" class="btn btn-default btn-xs btn-component" tabindex="0">Disable value</button>
    </div>
    <div class="display-flex gap-10 margin-bottom-15">
        <button type="button" class="btn btn-default btn-component" tabindex="0">Push event with gaPush</button>
        <button type="button" class="btn btn-default btn-component" tabindex="0">executeAndTrack counter: 0</button>
        <button type="button" class="btn btn-muted btn-component" tabindex="0">Clear dataLayer</button>
    </div>
    <pre class="bg-white border rounded padding-10 margin-bottom-0 text-size-12">[]</pre>
</div>
```