Setting up site analytics

Besides page views and events, [site search] can be tracked to better
understand how people use your documentation and what they expect to find.
In order to enable site search tracking, the following steps are required:

1. Go to your Google Analytics __admin settings__
2. Select the property for the respective tracking code
3. Select the __data streams__ tab and click the corresponding URL
4. Click the gear icon within the __enhanced measurement__ section
5. Ensure that __site search__ is enabled

To visualize feedback ratings you'll need to create a custom report with
[Google Analytics] that will quickly show you the worst- and best-rated
pages of your project documentation.

1.  Go to your Google Analytics __dashboard__

2.  Go to the __configure__ page on the left hand menu, then select
    __custom definitions__

3.  Click the __custom metrics__ tab and then __create custom metrics__,
    enter the following values:

    * Metric name: Page helpful
    * Description: Was this page helpful?
    * Event parameter: `data`
    * Unit of measurement: Standard

4.  Go to the __explore__ page on the left hand menu, create a new
    __blank exploration__

5.  Configure the report as follows:

    * Dimensions: Add `Event name` and `Page location`
    * Metrics: Add `Event count` and `Page helpful`
      (the custom metric created in step 3)
    * Rows: `Page location`
    * Values: Drag in both `Event count` and `Page helpful`
    * Filters: Add a new filter for
      `Event name / exactly matches / feedback`

!!! warning "Delay in data availability"

    The report may take 24 hours or longer to begin displaying data

Now, after you've saved the report and collected some feedback ratings,
you'll have a list of all pages with the total number of ratings, and an
average rating per page. This should help you identify pages that need to
be improved:

!!! danger "Google Analytics 4 does not support average values"

    To our knowledge, Google Analytics 4 has currently no feature that
    allows to define a custom calculated metric to compute the average
    rating of a page. See #5740.

[![feedback report]][feedback report]

* :material-emoticon-happy-outline: + :material-emoticon-sad-outline: – `material/emoticon-happy-outline` + `material/emoticon-sad-outline`
* :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
* :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`

- `{url}` – Page URL
- `{title}` – Page title

```
https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}
```

In this example, when clicking the link, the user is redirected to the "new
issue" form of your repository, with a pre-filled title including the path
of the current document, e.g.:

```
[Feedback] Setting up site analytics – /setup/setting-up-site-analytics/
```

An alternative to GitHub issues is [Google Forms].

``` html
<script>
  /* Add custom analytics integration here, e.g. */
  var property = "{{ config.extra.analytics.property }}" // (1)!

  /* Wait for page to load and application to mount */
  document.addEventListener("DOMContentLoaded", function() {
    location$.subscribe(function(url) {
      /* Add custom page event tracking here */ // (2)!
    })
  })
</script>
```

1.  As an example, this variable receives the value set in `mkdocs.yml`,
    which is `"foobar"` for `property`.
2.  If you're using [instant loading], you can use the `location$`
    observable to listen for navigation events, which always emits the
    current `URL`.

``` yaml
extra:
  analytics:
    provider: custom
    property: foobar # (1)!
```

1.  You can add arbitrary key-value combinations to configure your
    custom integration. This is especially useful if you're sharing the
    custom integration across multiple repositories.

``` js
var feedback = document.forms.feedback
feedback.hidden = false // (1)!

feedback.addEventListener("submit", function(ev) {
  ev.preventDefault()

  var page = document.location.pathname // (2)!
  var data = ev.submitter.getAttribute("data-md-value")

  console.log(page, data) // (3)!

  feedback.firstElementChild.disabled = true // (4)!

  var note = feedback.querySelector(
    ".md-feedback__note [data-md-value='" + data + "']"
  )
  if (note)
    note.hidden = false // (5)!
})
```

1.  The feedback widget is hidden by default so that it does not appear when
    people have JavaScript turned off. So, it needs to be turned on here.

2.  Retrieve page and feedback value.

3.  Replace this with the code that sends the data off to your analytics
    provider.

4.  Disable the form after submission.

5.  Show the configured notes. Which one is shown depends on the user
    feedback.

``` yaml
extra_javascript:
  - javascripts/feedback.js
```