# @frontity/google-analytics

Analytics package to use [Google Analytics](https://analytics.google.com/) with Frontity

## Table of Contents

* [Install](/frontity-packages/features-packages/analytics/google-analytics.md#install)
* [Settings](/frontity-packages/features-packages/analytics/google-analytics.md#settings)
* [Usage](/frontity-packages/features-packages/analytics/google-analytics.md#usage)
  * [`actions.analytics.pageview`](/frontity-packages/features-packages/analytics/google-analytics.md#actions-analytics-pageview)
  * [`actions.analytics.event`](/frontity-packages/features-packages/analytics/google-analytics.md#actions-analytics-event)

## Install

```bash
npm i @frontity/google-analytics
```

## Settings

The [namespace](https://docs.frontity.org/learning-frontity/namespaces) for this package is **`googleAnalytics`**

Every Google Analytics account has a [Tracking ID](https://support.google.com/analytics/answer/7372977?hl=en).\
To connect the package with a specific account (or accounts) we can set the following properties in the `frontity.settings.js`:

* `state.googleAnalytics.trackingId`: to specify just one *tracking ID*
* `state.googleAnalytics.trackingIds`: to specify a list of tracking ID's

```javascript
export default {
  packages: [
    {
      name: "@frontity/google-analytics",
      state: {
        googleAnalytics: {
          trackingId: "UA-12345678-9",
        },
      },
    },
  ],
};
```

```javascript
export default {
  packages: [
    {
      name: "@frontity/google-analytics",
      state: {
        googleAnalytics: {
          trackingIds: ["UA-34567890-12", "UA-34567890-13"],
        },
      },
    },
  ],
};
```

## Usage

This `@frontity/google-analytics` package can co-exist with some other `analytics` packages. Once we have properly installed and configured these `analytics` packages, their actions will be centralized by the `analytics` namespace

* `actions.analytics.pageview()` will take into account settings in `state.analytics.pageviews`
* `actions.analytics.event()` will take into account settings in `state.analytics.events`

> Read more [here](/frontity-packages/features-packages/analytics.md#how-to-use) about how to use Analytic packages

### `actions.analytics.pageview`

If `@frontity/google-analytics` is configured and enabled for *pageviews* in `state.analytics.pageviews`, every time a link changes (or every time `action.router.set(link)` is launched) a tracking for that page will be sent to Google Analytics by using internally `actions.analytics.pageview()`

### `actions.analytics.event`

If `@frontity/google-analytics` is configured and enabled for *events* in `state.analytics.events`, every time you call the method `actions.analytics.event()` from any of your React components, the proper tracking info will be sent to Google Analytics.

The `actions.analytics.event()` must receive an event object with the following properties.

| Name          | Type   | Required | Description                                                                                                                                                                                       |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`name`**    | string | yes      | The value of this property is mapped to the [`eventAction`](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#eventAction) field of `analytics.js` events. |
| **`payload`** | object | yes      | Event payload.                                                                                                                                                                                    |

The `payload` object has to have the following format:

| Name           | Type   | Required | Description                                                                                                                                                                                           |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`category`** | string | yes      | The value of this property is mapped to the [`eventCategory`](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#eventCategory) field of `analytics.js` events. |
| `label`        | string | no       | The value of this property is mapped to the [`eventLabel`](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#eventLabel) field of `analytics.js` events.       |
| `value`        | number | no       | The value of this property is mapped to the [`eventValue`](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#eventValue) field of `analytics.js` events.       |
| `[key]`        | any    | no       | Any other property specified in [`analytics.js` field reference](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference).                                           |

These values will be transfomed (by this package) into the proper format before sending the data to Google Analytics


---

# 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://api.frontity.org/frontity-packages/features-packages/analytics/google-analytics.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.