add @aptabase/browser

goenning · goenning · commit 348898fc82c8 · 2023-12-15T20:45:30.000Z
diff --git a/examples/plasmo-browserext/assets/icon.png b/examples/plasmo-browserext/assets/icon.png
diff --git a/examples/plasmo-browserext/background.ts b/examples/plasmo-browserext/background.ts
@@ -0,0 +1,5 @@
+import { init, trackEvent } from '@aptabase/browser';
+
+init('A-DEV-0000000000');
+
+trackEvent('background_service_started');
diff --git a/examples/plasmo-browserext/package.json b/examples/plasmo-browserext/package.json
@@ -0,0 +1,32 @@
+{
+  "name": "plasmo-browserext",
+  "displayName": "Plasmo browserext",
+  "version": "0.0.1",
+  "description": "A basic Plasmo extension.",
+  "author": "Plasmo Corp. <foss@plasmo.com>",
+  "scripts": {
+    "dev": "plasmo dev",
+    "build": "plasmo build",
+    "test": "plasmo test"
+  },
+  "dependencies": {
+    "plasmo": "0.84.0",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "@aptabase/browser": "*"
+  },
+  "devDependencies": {
+    "@types/chrome": "0.0.254",
+    "@types/react": "18.2.45",
+    "@types/react-dom": "18.2.17",
+    "typescript": "5.3.3"
+  },
+  "manifest": {
+    "permissions": [
+      "storage"
+    ],
+    "host_permissions": [
+      "https://*/*"
+    ]
+  }
+}
diff --git a/examples/plasmo-browserext/popup.tsx b/examples/plasmo-browserext/popup.tsx
@@ -0,0 +1,25 @@
+import { trackEvent } from '@aptabase/browser';
+import { useState } from 'react';
+
+function IndexPopup() {
+  const [count, setCount] = useState(0);
+
+  function increment() {
+    trackEvent('increment', { count: count + 1 });
+    setCount((c) => c + 1);
+  }
+
+  function decrement() {
+    trackEvent('decrement', { count: count - 1 });
+    setCount((c) => c - 1);
+  }
+
+  return (
+    <div>
+      <button onClick={increment}>Increment</button>
+      <button onClick={decrement}>decrement</button>
+    </div>
+  );
+}
+
+export default IndexPopup;
diff --git a/examples/plasmo-browserext/tsconfig.json b/examples/plasmo-browserext/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "plasmo/templates/tsconfig.base",
+  "exclude": ["node_modules"],
+  "include": [".plasmo/index.d.ts", "./**/*.ts", "./**/*.tsx"],
+  "compilerOptions": {
+    "paths": {
+      "~*": ["./*"]
+    },
+    "baseUrl": "."
+  }
+}
diff --git a/packages/browser/CHANGELOG.md b/packages/browser/CHANGELOG.md
@@ -0,0 +1,3 @@
+## 0.1.0
+
+- Initial version of the Aptabase SDK for Browser Extensions
diff --git a/packages/browser/LICENSE b/packages/browser/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Sumbit Labs Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/browser/README.md b/packages/browser/README.md
@@ -0,0 +1,44 @@
+![Aptabase](https://aptabase.com/og.png)
+
+# Aptabase SDK for Browser Extensions
+
+A tiny SDK (1 kB) to instrument your Browser/Chrome extensions with Aptabase, an Open Source, Privacy-First and Simple Analytics for Mobile, Desktop and Web Apps.
+
+## Install
+
+Install the SDK using npm or your preferred JavaScript package manager
+
+```bash
+npm add @aptabase/browser
+```
+
+## Usage
+
+First you need to get your `App Key` from Aptabase, you can find it in the `Instructions` menu on the left side menu.
+
+Initialize the SDK in your `Background Script` using your `App Key`:
+
+```js
+import { init } from '@aptabase/browser';
+
+init('<YOUR_APP_KEY>'); // 👈 this is where you enter your App Key
+```
+
+The init function also supports an optional second parameter, which is an object with the `isDebug` property. Your data is seggregated between development and production environments, so it's important to set this value correctly. By default the SDK will use the `NODE_ENV` environment variable to determine if it's in development or production mode, which is only available in bundlers like Webpack, Rollup, etc. If you're not using a bundler, you can pass in the `isDebug` property manually.
+
+Afterwards you can start tracking events with `trackEvent` from anywhere in your extension:
+
+```js
+import { trackEvent } from '@aptabase/browser';
+
+trackEvent('connect_click'); // An event with no properties
+trackEvent('play_music', { name: 'Here comes the sun' }); // An event with a custom property
+```
+
+A few important notes:
+
+1. The SDK will automatically enhance the event with some useful information, like the OS, the app version, and other things.
+2. You're in control of what gets sent to Aptabase. This SDK does not automatically track any events, you need to call `trackEvent` manually.
+   - Because of this, it's generally recommended to at least track an event at startup
+3. You do not need to await the `trackEvent` function, it'll run in the background.
+4. Only strings and numeric values are allowed on custom properties
diff --git a/packages/browser/package.json b/packages/browser/package.json
@@ -0,0 +1,36 @@
+{
+  "name": "@aptabase/browser",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Browser Extension SDK for Aptabase: Open Source, Privacy-First and Simple Analytics for Mobile, Desktop and Web Apps",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aptabase/aptabase-js.git",
+    "directory": "packages/browser"
+  },
+  "bugs": {
+    "url": "https://github.com/aptabase/aptabase-js/issues"
+  },
+  "homepage": "https://github.com/aptabase/aptabase-js",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist",
+    "package.json"
+  ]
+}
diff --git a/packages/browser/src/global.d.ts b/packages/browser/src/global.d.ts
@@ -0,0 +1,4 @@
+declare var aptabase: {
+  init: Function;
+  trackEvent: Function;
+};
diff --git a/packages/browser/src/index.ts b/packages/browser/src/index.ts
@@ -0,0 +1,82 @@
+import { newSessionId, sendEvent, validateAppKey, type AptabaseOptions } from '../../shared';
+
+// Session expires after 1 hour of inactivity
+const SESSION_TIMEOUT = 1 * 60 * 60;
+const sdkVersion = `aptabase-browser@${process.env.PKG_VERSION}`;
+const isWebContext = 'document' in globalThis;
+
+let _appKey = '';
+let _options: AptabaseOptions | undefined;
+
+globalThis.aptabase = {
+  init,
+  trackEvent,
+};
+
+export function init(appKey: string, options?: AptabaseOptions) {
+  if (isWebContext) {
+    console.error('@aptabase/browser can only be initialized in your background script.');
+    return;
+  }
+
+  if (!validateAppKey(appKey)) return;
+
+  _appKey = appKey;
+  _options = { ...options, appVersion: options?.appVersion ?? chrome.runtime.getManifest().version };
+
+  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+    if (message && message.type === '__aptabase__trackEvent') {
+      trackEvent(message.eventName, message.props);
+    }
+  });
+}
+
+export async function trackEvent(eventName: string, props?: Record<string, string | number | boolean>): Promise<void> {
+  if (isWebContext) {
+    return chrome.runtime.sendMessage({ type: '__aptabase__trackEvent', eventName, props });
+  }
+
+  const sessionId = await getSessionId();
+
+  return sendEvent({
+    sessionId,
+    appKey: _appKey,
+    isDebug: _options?.isDebug,
+    appVersion: _options?.appVersion,
+    sdkVersion,
+    eventName,
+    props,
+  });
+}
+
+type CachedItem = {
+  id: string;
+  lastTouched: number;
+};
+
+let _sessionId = newSessionId();
+
+async function getSessionId(): Promise<string> {
+  const now = Date.now();
+
+  // If storage is not available, return the in memory session id
+  // This id will be recreated if the extension is reloaded or the service worker becomes inactive
+  if (!chrome?.storage?.local) return _sessionId;
+
+  return new Promise((resolve) => {
+    chrome.storage.local.get('_ab_session_id', (result) => {
+      let item = (result['_ab_session_id'] as CachedItem) ?? { id: _sessionId, lastTouched: Date.now() };
+
+      const diffInMs = now - item.lastTouched;
+      const diffInSec = Math.floor(diffInMs / 1000);
+      if (diffInSec > SESSION_TIMEOUT) {
+        item.id = newSessionId();
+      }
+      item.lastTouched = now;
+
+      chrome.storage.local.set({ _ab_session_id: item }, () => {
+        resolve(item.id);
+      });
+    });
+  });
+}
diff --git a/packages/browser/tsconfig.json b/packages/browser/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "strict": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "types": ["@types"]
+    },
+    "declaration": true,
+    "declarationDir": "./dist"
+  }
+}
diff --git a/packages/browser/tsup.config.ts b/packages/browser/tsup.config.ts
@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsup';
+const { version } = require('./package.json');
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  minify: true,
+  sourcemap: true,
+  clean: true,
+  env: {
+    PKG_VERSION: version,
+  },
+});
diff --git a/packages/shared.ts b/packages/shared.ts
@@ -1,6 +1,7 @@
 const defaultLocale = getBrowserLocale();
 const defaultIsDebug = getIsDebug();
 const isInBrowser = typeof window !== 'undefined' && typeof window.fetch !== 'undefined';
+const isInBrowserExtension = typeof chrome !== 'undefined' && !!chrome.runtime.id;
 
 let _sessionId = newSessionId();
 let _lastTouched = new Date();
@@ -79,7 +80,7 @@ export async function sendEvent(opts: {
   eventName: string;
   props?: Record<string, string | number | boolean>;
 }): Promise<void> {
-  if (!isInBrowser) {
+  if (!isInBrowser && !isInBrowserExtension) {
     console.warn(`Aptabase: trackEvent requires a browser environment. Event "${opts.eventName}" will be discarded.`);
     return;
   }

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+## 0.1.0`
	`2`	`+`
	`3`	`+- Initial version of the Aptabase SDK for Browser Extensions`