From bd41b280e91c8d35edc4f9392c83f631996bbdd3 Mon Sep 17 00:00:00 2001 From: Felipe Rivera Cienfuegos Date: Tue, 21 Oct 2025 15:33:36 -0300 Subject: [PATCH 1/2] feat: add custom user ID support and opaque user ID handling - Introduced a new optional section in README.md for custom user ID configuration. - Implemented `getOpaqueUserId` function in user-id.ts to retrieve user IDs for auction requests. - Updated auction.ts to utilize the opaque user ID if available. - Modified Auction type in types.ts to include an optional `opaqueUserId` field. --- CHANGELOG.md | 6 ++++++ README.md | 19 +++++++++++++++++++ src/auction.ts | 7 +++++++ src/index.ts | 1 + src/types.ts | 1 + src/user-id.ts | 19 +++++++++++++++++++ 6 files changed, 53 insertions(+) create mode 100644 src/user-id.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index d10be3d..327c93a 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 09b48ff..7f38af1 100644 --- a/README.md +++ b/README.md @@ -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: "", + 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`. diff --git a/src/auction.ts b/src/auction.ts index 0f0dd7c..1ef7dec 100644 --- a/src/auction.ts +++ b/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", diff --git a/src/index.ts b/src/index.ts index a08866f..12f8bea 100644 --- a/src/index.ts +++ b/src/index.ts @@ -21,6 +21,7 @@ declare global { TS: { readonly token: string; readonly url?: string; + getUserId?: () => string; }; } } diff --git a/src/types.ts b/src/types.ts index acc0214..9d56249 100644 --- a/src/types.ts +++ b/src/types.ts @@ -12,6 +12,7 @@ export interface Auction { location: string; }; searchQuery?: string; + opaqueUserId?: string; } /** The banner object returned from the auction request */ diff --git a/src/user-id.ts b/src/user-id.ts new file mode 100644 index 0000000..05ea88b --- /dev/null +++ b/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; +} From 49463340d818739a463132ba1523ce6853fe41d8 Mon Sep 17 00:00:00 2001 From: Felipe Rivera Cienfuegos Date: Tue, 21 Oct 2025 15:34:38 -0300 Subject: [PATCH 2/2] chore: bump version to 0.6.0 and update README for new version --- README.md | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7f38af1..87aad46 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Directly from unpkg.com