Matomo for Nuxt

• ✨  Release Notes

Quick Setup

1. Add @openmost/nuxt-matomo dependency to your project

# Using pnpm
pnpm add @openmost/nuxt-matomo

# Using yarn
yarn add @openmost/nuxt-matomo

# Using npm
npm install @openmost/nuxt-matomo

2. Add @openmost/nuxt-matomo to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    '@openmost/nuxt-matomo'
  ]
})

3. Register config in the matomo section to your nuxt.config.ts:

runtimeConfig: {
  public: {
    matomo: {
      host: 'https://matomo.example.com',
      containerId: 'xxxxxxxx',
    },
  },
}

4. You can override values with .env file:

NUXT_PUBLIC_MATOMO_HOST=https://matomo.example.com
NUXT_PUBLIC_MATOMO_CONTAINER_ID=xxxxxxxx

5. Update your Matomo page view tag configuration

As SPA doesn't work with Matomo Tag Manager by default, you have to add a second trigger to your Matomo tag in the Tag Manager UI.

• Look at your Matomo Tag Manager container configuration
• Edit Matomo Analytics tag, and add a new "History change" trigger.
• Ensure that your tag has now both "Page view" AND "History change" triggers.
• Don't forget to publish a new version of your container!

Default dataLayer on every pages

On every pages, the default dataLayer object is generated with this structure :

dataLayer.push({
  event: 'page_view',
  page_url: '/', //example value
  referrer_url: '/previous' //example value
})

Useful composables

This module allow you to use some helpful composables, here is the list :

Add data to your dataLayer with the useDataLayerPush composable

The useDataLayerPush() composable allow you to easely push data to the dataLayer array.

<template>
  <button @click="onClick">Click me</button>
</template>

<script setup>
function onClick(){
  useDataLayerPush({
    event: 'some_event',
    foo: 'bar',
  })
}
</script>

Send events with the useMatomoEvent composable

The useMatomoEvent() composable allow you to send events to Matomo directly from your components.

It also handle custom dimension as 5th parameter (optional).

<template>
  <button @click="onClick">Click me</button>
</template>

<script setup>
function onClick(){
  useMatomoEvent('Category', 'Action', 'event_name', 23, {dimension1: 'Some value'})
}
</script>

Convert goals with the useMatomoGoal composable

The useMatomoGoal() composable allow you to convert goals from your components.

<template>
  <button @click="onClick">Click me</button>
</template>

<script setup>
function onClick(){
  useMatomoGoal(4) // 4 is the goal ID
}
</script>

Handle custom dimensions with the useMatomoCustomDimension composable

The useMatomoCustomDimension() composable allow you to send data to your custom dimensions.

<template>
  <button @click="onClick">Click me</button>
</template>

<script setup>
  function onClick() {
    useMatomoCustomDimension(1, 'My custom value') // 1 is the custom dimension ID
  }
</script>

Support custom variables with the useMatomoCustomVariables composable

The useMatomoCustomVariables() composable allow you to send data to your custom variables.

<template>
  <button @click="onClick">Click me</button>
</template>

<script setup>
  function onClick() {
    useMatomoCustomVariables(1, 'variable name', 'variable value', 'page') 
  }
</script>

Enjoy !