nuxt-gtag - npm Package Compare versions

Comparing version 0.6.3 to 1.0.0

dist/module.json

 {
   "name": "nuxt-gtag",
-  "version": "0.6.3",
+  "version": "1.0.0",
   "configKey": "gtag",
@@ -5,0 +5,0 @@ "compatibility": {

dist/runtime/composables/useGtag.d.ts

@@ -1,2 +0,7 @@
-import type { Gtag } from '../types';
-export declare function useGtag(): Gtag;
+import type { Gtag, UseGtagConsentOptions } from '../types';
+export declare function useGtag(): {
+    gtag: Gtag;
+    setConsent: (options: UseGtagConsentOptions) => void;
+    grantConsent: (id?: string) => void;
+    revokeConsent: (id?: string) => void;
+};

dist/runtime/gtag.d.ts

 export declare function gtag(..._args: any[]): void;
+/**
+ * Initialize the Google Analytics script.
+ */
+export declare function initGtag({ id, config }: {
+    id: string;
+    config: any;
+}): void;
+/**
+ * Disable Google Analytics.
+ *
+ * The Google tag (gtag.js) library includes a `window['ga-disable-MEASUREMENT_ID']`
+ * property that, when set to `true`, turns off the Google tag from sending data.
+ *
+ * @see https://developers.google.com/analytics/devguides/collection/gtagjs/user-opt-out
+ */
+export declare function disableGtag(id: string): void;
+/**
+ * Enable Google Analytics if it was disabled before.
+ */
+export declare function enableGtag(id: string): void;

package.json

 {
   "name": "nuxt-gtag",
   "type": "module",
-  "version": "0.6.3",
+  "version": "1.0.0",
   "packageManager": "pnpm@8.7.4",
@@ -6,0 +6,0 @@ "description": "Nuxt 3 module to natively integrate Google Analytics",

README.md

@@ -1,2 +0,2 @@
-![Nuxt Gtag module](./.github/og.png)
+![Nuxt Gtag module](./.github/og.jpg)
 
@@ -7,3 +7,3 @@ # Nuxt Gtag
 
-> [Nuxt 3](https://nuxt.com) module to integrate [Google Analytics 4](https://developers.google.com/analytics/devguides/collection/ga4?hl=en).
+> [Nuxt](https://nuxt.com) module to integrate [Google Analytics 4](https://developers.google.com/analytics/devguides/collection/ga4?hl=en).
 
@@ -26,2 +26,5 @@ ## Features
 npm i -D nuxt-gtag
+
+# yarn
+yarn add -D nuxt-gtag
 ```
@@ -46,6 +49,5 @@
 
-> **Note**
+> [!NOTE]
+> Ensure that the **Enhanced measurement** feature is enabled to allow `gtag.js` to automatically track page changes based on browser history events in Nuxt.
 >
-> Ensure that the **Enhanced measurement** feature is enabled to allow Gtag to automatically track page changes based on browser history events in Nuxt.
->
 > To enable this feature:
@@ -67,3 +69,5 @@ >
   gtag: {
+    // The Google Analytics 4 property ID to use for tracking
     id: 'G-XXXXXXXXXX',
+    // Additional configuration for the Google Analytics 4 property
     config: {
@@ -76,2 +80,13 @@ page_title: 'My Custom Page Title'
 
+### Runtime Config
+
+Instead of hard-coding your measurement ID in your Nuxt configuration, you can set your desired option in your project's `.env` file, leveraging [automatically replaced public runtime config values](https://nuxt.com/docs/api/configuration/nuxt-config#runtimeconfig) by matching environment variables at runtime.
+
+```ini
+# Overwrites the `gtag.id` module option
+NUXT_PUBLIC_GTAG_ID=G-XXXXXXXXXX
+```
+
+With this setup, you can omit the `gtag` key in your Nuxt configuration if you only intend to set the measurement ID.
+
 ### Consent Management
@@ -92,8 +107,10 @@
 
-To manually manage consent, you can use the [`useGtagConsent` composable](#usegtagconsent) to set the consent state, e.g. after the user has accepted your cookie policy.
+To manually manage consent, you can use the [`grantConsent` method destructurable from `useGtag`](#usegtag) to set the consent state, e.g. after the user has accepted your cookie policy.
 
 ```vue
 <script setup lang="ts">
+const { gtag, grantConsent, revokeConsent } = useGtag()
+
 function acceptTracking() {
-  useGtagConsent({ hasConsent: true })
+  grantConsent()
 }
@@ -109,13 +126,12 @@ </script>
 
-### Runtime Config
+You can even leave the measurement ID in your Nuxt config blank and set it dynamically later in your application by passing your ID as the first argument to `grantConsent`. This is especially useful if you want to use a custom ID for each user or if your app manages multiple tenants.
 
-Alternatively, leveraging [automatically replaced public runtime config values](https://nuxt.com/docs/api/configuration/nuxt-config#runtimeconfig) by matching environment variables at runtime, set your desired option in your project's `.env` file:
+```ts
+const { gtag, grantConsent, revokeConsent } = useGtag()
 
-```bash
-# Sets the `gtag.id` module option
-NUXT_PUBLIC_GTAG_ID=G-XXXXXXXXXX
+function acceptTracking() {
+  grantConsent('G-XXXXXXXXXX')
+}
 ```
 
-With this setup, you can omit the `gtag` key in your Nuxt configuration if you only want to set the measurement ID.
-
 ## Module Options
@@ -136,19 +152,44 @@
 
-The `useGtag` composable is SSR-safe and can be used to call any of the [gtag.js methods](https://developers.google.com/tag-platform/gtagjs/reference).
+The SSR-safe `useGtag` composable provides access to:
 
+- The `gtag.js` instance
+- The `grantConsent` method
+- The `revokeConsent` method
+
+It can be used as follows:
+
 ```ts
 // SSR-ready
-const gtag = useGtag()
-gtag(
-  // <command>,
-  // <command-parameters>
-)
+const { gtag } = useGtag()
+gtag('<command>', '<command-parameters>')
 ```
 
-> ℹ️ Since the Gtag instance is available in the client only, any `gtag()` (assuming the variable from above) calls executed on the server will have no effect.
+**Type Declarations**
 
+```ts
+function useGtag(): {
+  gtag: Gtag
+  grantConsent: (id?: string) => void
+  revokeConsent: (id?: string) => void
+}
+```
+
+#### `gtag`
+
+The `gtag` function is the main interface to the `gtag.js` instance and can be used to call any of the [gtag.js methods](https://developers.google.com/tag-platform/gtagjs/reference).
+
+```ts
+const { gtag } = useGtag()
+
+// SSR-ready
+gtag('<command>', '<command-parameters>')
+```
+
+> [!NOTE]
+> Since the `gtag.js` instance is available in the client only, any `gtag()` calls executed on the server will have no effect.
+
 **Type Declarations**
 
 ```ts
-function useGtag(): {
+function gtag(): {
   (command: 'config', targetId: string, config?: Record<string, any>): void
@@ -169,4 +210,5 @@ (command: 'event', eventName: string, eventParams?: Record<string, any>): void
 ```ts
+const { gtag } = useGtag()
+
 // SSR-ready
-const gtag = useGtag()
 gtag('event', 'screen_view', {
@@ -178,41 +220,43 @@ app_name: 'My App',
 
-### `useGtagConsent`
+#### `grantConsent`
 
-If you want to manually manage consent, i.e. for GDPR compliance, you can use the `useGtagConsent` composable to set the consent state. This composable accepts a single argument, an object with the following properties:
+If you want to manually manage consent, i.e. for GDPR compliance, you can use the `grantConsent` method to grant the consent. Make sure to set `initialConsent` to `false` in the module options beforehand.
 
-- `hasConsent` (optional): Whether to accept or decline the consent. Defaults to `true`.
-- `id` (optional): In case you want to initialize a custom Gtag ID. Make sure to set `initialConsent` to `false` in the module options beforehand.
+This function accepts an optional ID in case you want to initialize a custom Gtag ID and haven't set it in the module options.
 
-If the user has consented, the `gtag.js` script will be loaded and tracking will begin.
+```ts
+const { grantConsent } = useGtag()
 
-This is only necessary if you have disabled the `initialConsent` option.
+// When called, the `gtag.js` script will be loaded and tracking will begin
+grantConsent()
+```
 
+> [!NOTE]
+> Although this method is SSR-safe, the `gtag.js` script will be loaded in the client only. Make sure to run this method in the client.
+
+**Type Declarations**
+
 ```ts
-useGtagConsent({
-  hasConsent: true
-})
+function grantConsent(id?: string): void
 ```
 
-> ℹ️ Since the Gtag instance is available in the client only, executing the composable on the server will have no effect.
+#### `revokeConsent`
 
-**Type Declarations**
+If a user has previously granted consent, you can use the `revokeConsent` method to revoke the consent. This will prevent the `gtag.js` script from tracking any events until the consent is granted again.
 
+This function accepts an optional ID in case you haven't set it in the module options. Make sure to pass the same ID that was used to grant the consent.
+
 ```ts
-interface UseGtagConsentOptions {
-  /**
-   * Whether to accept or decline the consent.
-   *
-   * @default true
-   */
-  hasConsent?: boolean
-  /**
-   * In case you want to initialize a custom Gtag ID. Make sure to set
-   * `initialConsent` to `false` in the module options beforehand.
-   */
-  id?: string
-}
+const { revokeConsent } = useGtag()
 
-function useGtagConsent(options: UseGtagConsentOptions): void
+// When called, the `gtag.js` script will be stopped from tracking events
+revokeConsent()
 ```
 
+**Type Declarations**
+
+```ts
+function revokeConsent(id?: string): void
+```
+
 ### `useTrackEvent`
@@ -222,6 +266,7 @@
 
-- The name of the recommended or custom event
-- A collection of parameters that provide additional information about the event (optional)
+- The name of the recommended or custom event.
+- A collection of parameters that provide additional information about the event (optional).
 
-> ℹ️ Since the Gtag instance is available in the client only, executing the composable on the server will have no effect.
+> [!NOTE]
+> This composable is SSR-ready. But since the `gtag.js` instance is available in the client only, executing the composable on the server will have no effect.
 
@@ -258,3 +303,3 @@ **Type Declarations**
 
-- [SVGBackgrounds.com](https://www.svgbackgrounds.com) for the OpenGraph image background pattern.
+- [Maronbeere](https://maronbeere.carrd.co) for his logo pixel art.
 
@@ -261,0 +306,0 @@ ## License

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

19867

increased by11.71%

Lines of code

239

increased by20.1%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

297

increased by17.86%

Worsened metrics

Number of package files

20

decreased by-9.09%

No dependency changes