feat: add custom user ID support and opaque user ID handling

CHANGELOG.md

@@ -1,3 +1,9 @@
+### 0.6.0
+
+- Add support for sending opaque user ID in auction requests
+- Integrate with analytics.js getUserId() for consistent user identification across auctions and events
+- Support custom user ID override via window.TS.getUserId()
+
 ### 0.3.0
 
 - Add multicategory query support.

README.md

@@ -13,7 +13,7 @@ Directly from unpkg.com
 <script
   async
   type="module"
-  src="https://unpkg.com/@topsort/banners@0.5.2/dist/banners.mjs"
+  src="https://unpkg.com/@topsort/banners@0.6.0/dist/banners.mjs"
 ></script>
 <script async type="module" src="https://unpkg.com/@topsort/analytics.js"></script>
 <script>
@@ -103,6 +103,25 @@ If multiple are set, only the first will be considered, in that order.
 | `resolvedBidId` | `string`                                    | The corresponding auction ID of the winning entity.                          |
 | `asset`         | `[{ url: string }]`                         | An array of url linking to the assets of the banner.                         |
 
+## Custom User ID (Optional)
+
+If you want to use your own user identification system instead of the automatic opaque user ID, you can override the `getUserId` function in the `window.TS` configuration.
+
+Your custom `getUserId` function should return the user's ID as a string. You are responsible for generating and persisting the ID (e.g., in a cookie or local storage).
+
+```javascript
+window.TS = {
+  token: "<your topsort api key>",
+  getUserId() {
+    // Return your custom user ID
+    // This will be used for both auction requests and event reporting
+    return globalUserId ?? generateAndStoreUserId();
+  },
+};
+```
+
+This configuration needs to be set before analytics.js is loaded or imported.
+
 # Listening to events
 The banner component emits an event when the state changes. You can listen to this event to write custom logic.
 The various states are `loading`, `ready`, `error`, and `nowinners`.

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@topsort/banners",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "A web component for displaying Topsort banner ads.",
   "type": "module",
   "author": "Topsort",

src/auction.ts

@@ -1,5 +1,6 @@
 import { TopsortRequestError } from "./errors";
 import type { Auction, Banner } from "./types";
+import { getOpaqueUserId } from "./user-id";
 
 export const getDeviceType = (): "mobile" | "desktop" => {
   const ua = navigator.userAgent;
@@ -29,6 +30,12 @@ export async function runAuction(
   const device = getDeviceType();
   const token = window.TS.token;
   const url = window.TS.url || "https://api.topsort.com";
+
+  const opaqueUserId = getOpaqueUserId();
+  if (opaqueUserId) {
+    auction.opaqueUserId = opaqueUserId;
+  }
+
   const res = await fetch(new URL(`${url}/v2/auctions`), {
     method: "POST",
     mode: "cors",

src/index.ts

@@ -21,6 +21,7 @@ declare global {
     TS: {
       readonly token: string;
       readonly url?: string;
+      getUserId?: () => string;
     };
   }
 }

src/types.ts

@@ -12,6 +12,7 @@ export interface Auction {
     location: string;
   };
   searchQuery?: string;
+  opaqueUserId?: string;
 }
 
 /** The banner object returned from the auction request */

src/user-id.ts

@@ -0,0 +1,19 @@
+/**
+ * Gets the opaque user ID for auction requests
+ * Uses analytics.js getUserId function if available
+ */
+
+/**
+ * Gets the opaque user ID to use for auctions
+ * Calls window.TS.getUserId() which is provided by analytics.js
+ * Returns undefined if analytics.js is not loaded or getUserId is not available
+ */
+export function getOpaqueUserId(): string | undefined {
+  // Use getUserId from analytics.js if available
+  if (window.TS?.getUserId && typeof window.TS.getUserId === "function") {
+    return window.TS.getUserId();
+  }
+
+  // Analytics.js not loaded yet or getUserId not available
+  return undefined;
+}