feat: add support for disabling tracking via localStorage

.playground/app.vue

@@ -28,6 +28,29 @@ function updateRefs() {
 function seePreview() {
   umTrackEvent('see-preview', { from: 'localhost' });
 }
+
+// is disabled via localStorage
+const idvls = ref(false);
+let storage: Storage | undefined;
+let refresh = function () {};
+
+watch(idvls, (status) => {
+  storage?.setItem('umami.disabled', String(+status));
+  // refresh to apply changes
+  refresh();
+  // better user perf than watching localStorage
+});
+
+onMounted(() => {
+  storage = localStorage;
+  idvls.value = storage?.getItem('umami.disabled') === '1';
+  nextTick().then(() => {
+    // real refresh fn here to prevent loop :)
+    refresh = function () {
+      navigateTo('/', { replace: true, external: true });
+    };
+  });
+});
 </script>
 
 <template>
@@ -75,6 +98,18 @@ function seePreview() {
           Page {{ i }}
         </NuxtLink>
       </div>
+
+      <div class="deck">
+        <div>
+          <input
+            id="umami-disabled"
+            v-model="idvls"
+            name="umami-disabled"
+            type="checkbox"
+          >
+          <label for="umami-disabled">Disable Umami via localStorage</label>
+        </div>
+      </div>
     </div>
   </div>
 </template>
@@ -132,4 +167,13 @@ h1 {
   flex-wrap: wrap;
   justify-content: center;
 }
+
+input {
+  margin: 0.4rem;
+}
+
+label, input {
+  user-select: none;
+  cursor: pointer;
+}
 </style>

internal/debug.ts

@@ -15,7 +15,8 @@ const warnings: Record<ErrorId, ErrorObj> = {
   'err-domain': { level: 'info', text: 'Tracking is disabled for this domain because it is not in the allowed domain config.' },
   'err-id': { level: 'error', text: '`id` is missing or incorrectly configured. Check Umami config.' },
   'err-host': { level: 'error', text: '`host` is missing or incorrectly configured. Check Umami config.' },
-  'err-local': { level: 'info', text: 'Tracking disabled on localhost' },
+  'err-localhost': { level: 'info', text: 'Tracking disabled on localhost' },
+  'err-local-storage': { level: 'info', text: 'Tracking disabled via local-storage' },
   'err-collect': { level: 'error', text: 'Uhm... Something went wrong and I have no clue.' },
   'err-directive': { level: 'error', text: 'Invalid v-umami directive value. Expected string or object with {key:value} pairs. See https://github.com/ijkml/nuxt-umami#available-methods' },
   'err-event-name': { level: 'warn', text: 'An Umami track event was fired without a name. `#unknown-event` will be used as event name.' },

internal/types.ts

@@ -95,7 +95,7 @@ type ViewPayload = BasicPayload;
 
 type PartialPayload = Omit<BasicPayload, 'website'>;
 type PayloadType = 'pageview' | 'event';
-type PreflightResult = 'ssr' | 'id' | 'host' | 'domain' | 'local' | true;
+type PreflightResult = 'ssr' | 'id' | 'host' | 'domain' | 'localhost' | 'local-storage' | true;
 
 interface ServerPayload {
   type: PayloadType;

internal/utils.ts

@@ -102,12 +102,15 @@ const preflight = computed((): PreflightResult => {
   if (!host || !isValidHost(endpoint.value))
     return 'host';
 
-  const {
-    location: { hostname },
-  } = window;
+  const hostname = window.location.hostname;
+  const storage = window.localStorage;
 
   if (ignoreLocal && hostname === 'localhost')
-    return 'local';
+    return 'localhost';
+
+  // Disable tracking when umami.disabled=1 in localStorage
+  if (storage.getItem('umami.disabled') === '1')
+    return 'local-storage';
 
   const domains = domainList.value;