fix(matomo): easier cloud config using cloudId

Fixes #279

Author: harlan-zw

docs/content/scripts/analytics/matomo-analytics.md

@@ -17,8 +17,9 @@ use the [useScriptMatomoAnalytics](#useScriptMatomoAnalytics) composable.
 
 ## Loading Globally
 
-If you don't plan to send custom events you can use the [Environment overrides](https://nuxt.com/docs/getting-started/configuration#environment-overrides) to
-disable the script in development.
+The following config assumes you're using Matomo Cloud with the default `siteId` of `1`. 
+
+If you're self-hosting, you'll need to provide the `matomoUrl` instead. If you have other sites you want to track, you can add them using `siteId`.
 
 ::code-group
 
@@ -27,7 +28,7 @@ export default defineNuxtConfig({
   scripts: {
     registry: {
       matomoAnalytics: {
-        siteId: 'YOUR_SITE_ID'
+        cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
       }
     }
   }
@@ -40,7 +41,7 @@ export default defineNuxtConfig({
     scripts: {
       registry: {
         matomoAnalytics: {
-          siteId: 'YOUR_SITE_ID',
+          cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
         }
       }
     }
@@ -61,8 +62,8 @@ export default defineNuxtConfig({
       scripts: {
         matomoAnalytics: {
           // .env
-          // NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_SITE_ID=<your-id>
-          siteId: '', // NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_SITE_ID
+          // NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_CLOUD_ID=<your-id>
+          cloudId: '', // NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_CLOUD_ID
         },
       },
     },
@@ -76,16 +77,52 @@ export default defineNuxtConfig({
 
 The `useScriptMatomoAnalytics` composable lets you have fine-grain control over when and how Matomo Analytics is loaded on your site.
 
+
+```ts
+const matomoAnalytics = useScriptMatomoAnalytics({
+  cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
+})
+```
+
+By default, a `siteId` of `1` is used and the page is not tracked. You can enable tracking by setting `trackPageView` to `true`.
+
+```ts
+const matomoAnalytics = useScriptMatomoAnalytics({
+  cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
+  trackPageView: true,
+  siteId: 2,
+})
+```
+
+If you'd like more control over the tracking, for example to set a custom dimension, you can send events using the `proxy` object.
+
+```ts
+const { proxy } = useScriptMatomoAnalytics({
+  cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
+})
+
+// set custom dimension
+proxy._paq.push(['setCustomDimension', 1, 'value'])
+// send page event
+proxy._paq.push(['trackPageView'])
+```
+
+Please see the [Config Schema](#config-schema) for all available options.
+
+### Using Matomo Self-Hosted
+
+For self-hosted Matomo, set `matomoUrl` to customize tracking, you may need to set the `trackerUrl` if you've customized this.
+
 ```ts
 const matomoAnalytics = useScriptMatomoAnalytics({
-  matomoUrl: 'YOUR_MATOMO_URL',
-  siteId: 'YOUR_SITE_ID'
+  // e.g. https://your-url.com/tracker.js & https://your-url.com//matomo.php both exists
+  matomoUrl: 'https://your-url.com',
 })
 ```
 
 ### Using Matomo Whitelabel
 
-For Matomo Whitelabel, set trackerUrl and scriptInput.src to customize tracking.
+For Matomo Whitelabel, set `trackerUrl` and `scriptInput.src` to customize tracking.
 
 ```ts
 const matomoAnalytics = useScriptMatomoAnalytics({
@@ -113,8 +150,8 @@ You must provide the options when setting up the script for the first time.
 ```ts
 // matomoUrl and site are required
 export const MatomoAnalyticsOptions = object({
-  matomoUrl: string(),
-  siteId: string(),
+  matomoUrl: optional(string()),
+  siteId: optional(string()),
   trackerUrl: optional(string()),
   trackPageView: optional(boolean()),
   enableLinkTracking: optional(boolean()),

playground/pages/third-parties/matomo-analytics/default.vue

@@ -0,0 +1,28 @@
+<script lang="ts" setup>
+import { useHead } from '#imports'
+
+useHead({
+  title: 'Matomo Analytics',
+  script: [
+    {
+      innerHTML: `var _paq = window._paq = window._paq || [];
+  /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+  _paq.push(['trackPageView']);
+  _paq.push(['enableLinkTracking']);
+  (function() {
+    var u="https://nuxt.matomo.cloud/";
+    _paq.push(['setTrackerUrl', u+'matomo.php']);
+    _paq.push(['setSiteId', '1']);
+    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
+    g.async=true; g.src='https://cdn.matomo.cloud/nuxt.matomo.cloud/matomo.js'; s.parentNode.insertBefore(g,s);
+  })();`,
+    },
+  ],
+})
+</script>
+
+<template>
+  <div>
+    matomo default
+  </div>
+</template>

playground/pages/third-parties/matomo-analytics.vue renamed to playground/pages/third-parties/matomo-analytics/nuxt-scripts.vue

@@ -7,7 +7,7 @@ useHead({
 
 // composables return the underlying api as a proxy object and the script state
 const { status, proxy } = useScriptMatomoAnalytics({
-  matomoUrl: 'https://nuxt-scripts-demo.matomo.cloud',
+  cloudId: 'nuxt.matomo.cloud',
   siteId: '1',
 })
 

src/runtime/registry/matomo-analytics.ts

@@ -1,11 +1,12 @@
-import { withBase, withHttps } from 'ufo'
+import { withBase, withHttps, withoutProtocol, withoutTrailingSlash } from 'ufo'
 import { useRegistryScript } from '../utils'
 import { boolean, object, optional, string } from '#nuxt-scripts-validator'
 import type { RegistryScriptInput } from '#nuxt-scripts'
 
 export const MatomoAnalyticsOptions = object({
   matomoUrl: optional(string()),
   siteId: string(),
+  cloudId: optional(string()),
   trackerUrl: optional(string()),
   trackPageView: optional(boolean()),
   enableLinkTracking: optional(boolean()),
@@ -23,42 +24,47 @@ declare global {
 }
 
 export function useScriptMatomoAnalytics<T extends MatomoAnalyticsApi>(_options?: MatomoAnalyticsInput) {
-  return useRegistryScript<T, typeof MatomoAnalyticsOptions>('matomoAnalytics', options => ({
-    scriptInput: {
-      src: withBase(`/matomo.js`, withHttps(options?.matomoUrl || '')),
-      crossorigin: false,
-    },
-    schema: import.meta.dev ? MatomoAnalyticsOptions : undefined,
-    scriptOptions: {
-      use() {
-        return { _paq: window._paq }
+  return useRegistryScript<T, typeof MatomoAnalyticsOptions>('matomoAnalytics', (options) => {
+    const normalizedCloudId = options?.cloudId ? withoutTrailingSlash(withoutProtocol(options.cloudId)) : undefined
+    const origin = options?.matomoUrl ? options.matomoUrl : `https://cdn.matomo.cloud/${normalizedCloudId}/`
+    const _paq = import.meta.client ? (window._paq = window._paq || []) : []
+    return {
+      scriptInput: {
+        src: withBase(`/matomo.js`, origin),
+        crossorigin: false,
       },
-      // allow _paq to be accessed on the server
-      stub: import.meta.client
+      schema: import.meta.dev ? MatomoAnalyticsOptions : undefined,
+      scriptOptions: {
+        use() {
+          return { _paq: window._paq }
+        },
+        // allow _paq to be accessed on the server
+        stub: import.meta.client
+          ? undefined
+          : ({ fn }) => {
+              return fn === '_paq' ? [] : undefined
+            },
+      },
+      clientInit: import.meta.server
         ? undefined
-        : ({ fn }) => {
-            return fn === '_paq' ? [] : undefined
+        : () => {
+            if (options?.enableLinkTracking) {
+              _paq.push(['enableLinkTracking'])
+            }
+            if (options?.disableCookies) {
+              _paq.push(['disableCookies'])
+            }
+            if (options?.trackerUrl || options?.matomoUrl) {
+              _paq.push(['setTrackerUrl', options?.trackerUrl ? withHttps(options.trackerUrl) : withBase(`/matomo.php`, withHttps(options?.matomoUrl || ''))])
+            }
+            else if (normalizedCloudId) {
+              _paq.push(['setTrackerUrl', withBase(`/matomo.php`, withHttps(normalizedCloudId))])
+            }
+            _paq.push(['setSiteId', String(options?.siteId) || '1'])
+            if (options?.trackPageView) {
+              _paq.push(['trackPageView'])
+            }
           },
-    },
-    clientInit: import.meta.server
-      ? undefined
-      : () => {
-          const _paq = window._paq = window._paq || []
-          if (options?.trackPageView) {
-            _paq.push(['trackPageView'])
-          }
-          if (options?.enableLinkTracking) {
-            _paq.push(['enableLinkTracking'])
-          }
-
-          if (options?.disableCookies) {
-            _paq.push(['disableCookies'])
-          }
-
-          if (options?.trackerUrl || options?.matomoUrl) {
-            _paq.push(['setTrackerUrl', options?.trackerUrl ? withHttps(options.trackerUrl) : withBase(`/matomo.php`, withHttps(options?.matomoUrl || ''))])
-          }
-          _paq.push(['setSiteId', options?.siteId || '1'])
-        },
-  }), _options)
+    }
+  }, _options)
 }