add push Matomo API

CHANGELOG.md

@@ -1,5 +1,15 @@
 # @mbinjamil/matomo-client
 
+## 0.2.0
+
+### Minor Changes
+
+- Add low level `push` Matomo API
+
+### Patch Changes
+
+- Add code documentation
+
 ## 0.1.3
 
 ### Patch Changes

package.json

@@ -1,9 +1,13 @@
 {
   "name": "@mbinjamil/matomo-client",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "A thin wrapper around Matomo analytics",
   "keywords": [
-    "analytics"
+    "matomo",
+    "tracking",
+    "analytics",
+    "javascript",
+    "react"
   ],
   "homepage": "https://github.com/binjamil/matomo-client",
   "bugs": {
@@ -24,9 +28,10 @@
   "module": "dist/matomo-client.esm.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "build": "npm run build:types && npm run build:js",
+    "build": "pnpm build:types && pnpm build:js",
     "build:js": "node build.mjs",
     "build:types": "tsc --emitDeclarationOnly",
+    "release": "pnpm build && pnpm changeset publish",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

src/index.ts

@@ -4,6 +4,12 @@ declare global {
   }
 }
 
+/**
+ * Injects the Matomo tracking script into the DOM and loads it asynchronously
+ *
+ * @param trackerUrl - Your Matomo URL
+ * @param siteId - Site ID of the website you are tracking in Matomo
+ */
 export const load = (trackerUrl: string, siteId: number): void => {
   let tracker = document.createElement("script");
   let firstScript =
@@ -18,23 +24,50 @@ export const load = (trackerUrl: string, siteId: number): void => {
 
   url.pathname = "/matomo.php";
   window._paq = window._paq || [];
-  window._paq.push(["enableLinkTracking"]);
-  window._paq.push(["setTrackerUrl", url.href]);
-  window._paq.push(["setSiteId", siteId]);
+  push(["enableLinkTracking"]);
+  push(["setTrackerUrl", url.href]);
+  push(["setSiteId", siteId]);
 
   firstScript.parentNode.insertBefore(tracker, firstScript);
 };
 
+/**
+ * Logs a page view. The URL is set to `window.location.href` because Matomo
+ * by default does not support client-side routing
+ *
+ * @param pageTitle - A custom title that overrides the default HTML page title
+ */
 export const trackPageView = (pageTitle?: string): void => {
-  window._paq.push(['setCustomUrl', window.location.href]);
-  window._paq.push(["trackPageView", pageTitle]);
+  push(["setCustomUrl", window.location.href]);
+  push(["trackPageView", pageTitle]);
 };
 
+/**
+ * Logs an event of interest
+ *
+ * @param category - An event category (Videos, Music, Games...)
+ * @param action - An event action (Play, Pause, Duration, Add Playlist, Downloaded, Clicked...)
+ * @param name - An optional event name
+ * @param value - An optional numeric value
+ */
 export const trackEvent = (
   category: string,
   action: string,
   name: string,
   value: number
 ): void => {
-  window._paq.push(["trackEvent", category, action, name, value]);
+  push(["trackEvent", category, action, name, value]);
+};
+
+/**
+ * Low-level Matomo API to execute any supported configuration or tracking calls
+ * @see https://developer.matomo.org/api-reference/tracking-javascript
+ *
+ * @param values - An array defining API method name and its parameters 
+ *
+ * @example
+ * push([ 'API_method_name', parameter_list ]);
+ */
+export const push = (values: ReadonlyArray<string | number>): void => {
+  window._paq.push(values);
 };