feat(electron): allow custom user agent for session activity

.changeset/electron-user-agent.md

@@ -0,0 +1,5 @@
+---
+"@clerk/electron": patch
+---
+
+Add a `userAgent` option to `createClerkBridge()` so Electron apps can customize the app name used for UserProfile session activity attribution while preserving platform details.

packages/electron/README.md

@@ -96,6 +96,16 @@ import { passkeys } from '@clerk/electron/passkeys';
 </ClerkProvider>;
 ```
 
+Pass `userAgent` to `createClerkBridge` before creating renderer windows to set an app-specific product token, such as `Acme Co/1.0.0`. Clerk preserves Electron's platform details, such as `Macintosh` or `Windows`, while using the product token for UserProfile session activity attribution:
+
+```ts
+createClerkBridge({
+ storage: storage(),
+ renderer: { scheme: 'my-app', host: 'renderer' },
+ userAgent: 'Acme Co/1.0.0',
+});
+```
+
 ## Content Security Policy
 
 `@clerk/electron` loads Clerk's prebuilt UI from Clerk's CDN at runtime rather than bundling it, so your renderer's Content Security Policy must allow Clerk's Frontend API host. If it doesn't, the UI script fails to load and Clerk components never render.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -10,6 +10,8 @@ vi.mock('electron', () => ({
  on: vi.fn(),
  removeListener: vi.fn(),
  setAsDefaultProtocolClient: vi.fn(),
+ userAgentFallback:
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  },
  ipcMain: {
  handle: vi.fn(),
@@ -42,6 +44,8 @@ describe('createClerkBridge', () => {
 
  beforeEach(() => {
  vi.clearAllMocks();
+ app.userAgentFallback =
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
  });
 
  it('requires a storage adapter', () => {
@@ -54,6 +58,28 @@ describe('createClerkBridge', () => {
  expect(ipcMain.handle).toHaveBeenCalledTimes(3);
  });
 
+ it('keeps the platform details when setting the app user-agent fallback', () => {
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has no platform details', () => {
+ app.userAgentFallback = 'Electron default';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has malformed platform details', () => {
+ app.userAgentFallback = 'Mozilla/5.0 ((((';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
  it('registers the configured renderer scheme as privileged before app ready', () => {
  createClerkBridge({
  storage,

packages/electron/src/main/create-clerk-bridge.ts

@@ -1,4 +1,4 @@
-import { protocol } from 'electron';
+import { app, protocol } from 'electron';
 
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
@@ -19,6 +19,21 @@ function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridge
  }
 }
 
+function buildUserAgentFallback(defaultUserAgent: string, productToken: string): string {
+ const platformCommentStart = defaultUserAgent.indexOf('(');
+ const platformCommentEnd = defaultUserAgent.indexOf(')', platformCommentStart + 1);
+
+ if (platformCommentStart === -1 || platformCommentEnd === -1) {
+ return productToken;
+ }
+
+ const platformComment = defaultUserAgent.slice(platformCommentStart, platformCommentEnd + 1);
+
+ // Clerk's session activity parser preserves the platform comment and treats the
+ // token after Gecko as the app/browser name.
+ return `Mozilla/5.0 ${platformComment} Gecko/20100101 ${productToken}`;
+}
+
 /**
  * Creates the Clerk bridge for Electron's main process.
  *
@@ -37,6 +52,10 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
  let cleanupOAuthTransport: (() => void) | undefined;
  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
+ if (options.userAgent) {
+ app.userAgentFallback = buildUserAgentFallback(app.userAgentFallback, options.userAgent);
+ }
+
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
 

packages/electron/src/shared/types.ts

@@ -22,6 +22,13 @@ export type CreateClerkBridgeOptions = {
  * the optional `@clerk/electron-passkeys` package and `exposeClerkBridge({ passkeys: true })`.
  */
  passkeys?: boolean;
+ /**
+ * Product token to use in Electron's user-agent fallback. Clerk uses the resulting
+ * user-agent for UserProfile session activity attribution when no webContents or
+ * session-level user-agent is set. The Electron platform comment is preserved so
+ * device details such as macOS or Windows can still be detected.
+ */
+ userAgent?: string;
 };
 
 export type ExposeClerkBridgeOptions = {

.changeset/electron-user-agent.md

@@ -0,0 +1,5 @@
+---
+"@clerk/electron": patch
+---
+
+Add a `userAgent` option to `createClerkBridge()` so Electron apps can customize the app name used for UserProfile session activity attribution while preserving platform details.

packages/electron/README.md

@@ -96,6 +96,16 @@ import { passkeys } from '@clerk/electron/passkeys';
 </ClerkProvider>;
 ```
 
+Pass `userAgent` to `createClerkBridge` before creating renderer windows to set an app-specific product token, such as `Acme Co/1.0.0`. Clerk preserves Electron's platform details, such as `Macintosh` or `Windows`, while using the product token for UserProfile session activity attribution:
+
+```ts
+createClerkBridge({
+ storage: storage(),
+ renderer: { scheme: 'my-app', host: 'renderer' },
+ userAgent: 'Acme Co/1.0.0',
+});
+```
+
 ## Content Security Policy
 
 `@clerk/electron` loads Clerk's prebuilt UI from Clerk's CDN at runtime rather than bundling it, so your renderer's Content Security Policy must allow Clerk's Frontend API host. If it doesn't, the UI script fails to load and Clerk components never render.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -10,6 +10,8 @@ vi.mock('electron', () => ({
  on: vi.fn(),
  removeListener: vi.fn(),
  setAsDefaultProtocolClient: vi.fn(),
+ userAgentFallback:
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  },
  ipcMain: {
  handle: vi.fn(),
@@ -42,6 +44,8 @@ describe('createClerkBridge', () => {
 
  beforeEach(() => {
  vi.clearAllMocks();
+ app.userAgentFallback =
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
  });
 
  it('requires a storage adapter', () => {
@@ -54,6 +58,28 @@ describe('createClerkBridge', () => {
  expect(ipcMain.handle).toHaveBeenCalledTimes(3);
  });
 
+ it('keeps the platform details when setting the app user-agent fallback', () => {
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has no platform details', () => {
+ app.userAgentFallback = 'Electron default';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has malformed platform details', () => {
+ app.userAgentFallback = 'Mozilla/5.0 ((((';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
  it('registers the configured renderer scheme as privileged before app ready', () => {
  createClerkBridge({
  storage,

packages/electron/src/main/create-clerk-bridge.ts

@@ -1,4 +1,4 @@
-import { protocol } from 'electron';
+import { app, protocol } from 'electron';
 
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
@@ -19,6 +19,21 @@ function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridge
  }
 }
 
+function buildUserAgentFallback(defaultUserAgent: string, productToken: string): string {
+ const platformCommentStart = defaultUserAgent.indexOf('(');
+ const platformCommentEnd = defaultUserAgent.indexOf(')', platformCommentStart + 1);
+
+ if (platformCommentStart === -1 || platformCommentEnd === -1) {
+ return productToken;
+ }
+
+ const platformComment = defaultUserAgent.slice(platformCommentStart, platformCommentEnd + 1);
+
+ // Clerk's session activity parser preserves the platform comment and treats the
+ // token after Gecko as the app/browser name.
+ return `Mozilla/5.0 ${platformComment} Gecko/20100101 ${productToken}`;
+}
+
 /**
  * Creates the Clerk bridge for Electron's main process.
  *
@@ -37,6 +52,10 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
  let cleanupOAuthTransport: (() => void) | undefined;
  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
+ if (options.userAgent) {
+ app.userAgentFallback = buildUserAgentFallback(app.userAgentFallback, options.userAgent);
+ }
+
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
 

packages/electron/src/shared/types.ts

@@ -22,6 +22,13 @@ export type CreateClerkBridgeOptions = {
  * the optional `@clerk/electron-passkeys` package and `exposeClerkBridge({ passkeys: true })`.
  */
  passkeys?: boolean;
+ /**
+ * Product token to use in Electron's user-agent fallback. Clerk uses the resulting
+ * user-agent for UserProfile session activity attribution when no webContents or
+ * session-level user-agent is set. The Electron platform comment is preserved so
+ * device details such as macOS or Windows can still be detected.
+ */
+ userAgent?: string;
 };
 
 export type ExposeClerkBridgeOptions = {

.changeset/electron-user-agent.md

@@ -0,0 +1,5 @@
+---
+"@clerk/electron": patch
+---
+
+Add a `userAgent` option to `createClerkBridge()` so Electron apps can customize the app name used for UserProfile session activity attribution while preserving platform details.

packages/electron/README.md

@@ -96,6 +96,16 @@ import { passkeys } from '@clerk/electron/passkeys';
 </ClerkProvider>;
 ```
 
+Pass `userAgent` to `createClerkBridge` before creating renderer windows to set an app-specific product token, such as `Acme Co/1.0.0`. Clerk preserves Electron's platform details, such as `Macintosh` or `Windows`, while using the product token for UserProfile session activity attribution:
+
+```ts
+createClerkBridge({
+ storage: storage(),
+ renderer: { scheme: 'my-app', host: 'renderer' },
+ userAgent: 'Acme Co/1.0.0',
+});
+```
+
 ## Content Security Policy
 
 `@clerk/electron` loads Clerk's prebuilt UI from Clerk's CDN at runtime rather than bundling it, so your renderer's Content Security Policy must allow Clerk's Frontend API host. If it doesn't, the UI script fails to load and Clerk components never render.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -10,6 +10,8 @@ vi.mock('electron', () => ({
  on: vi.fn(),
  removeListener: vi.fn(),
  setAsDefaultProtocolClient: vi.fn(),
+ userAgentFallback:
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  },
  ipcMain: {
  handle: vi.fn(),
@@ -42,6 +44,8 @@ describe('createClerkBridge', () => {
 
  beforeEach(() => {
  vi.clearAllMocks();
+ app.userAgentFallback =
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
  });
 
  it('requires a storage adapter', () => {
@@ -54,6 +58,28 @@ describe('createClerkBridge', () => {
  expect(ipcMain.handle).toHaveBeenCalledTimes(3);
  });
 
+ it('keeps the platform details when setting the app user-agent fallback', () => {
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has no platform details', () => {
+ app.userAgentFallback = 'Electron default';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has malformed platform details', () => {
+ app.userAgentFallback = 'Mozilla/5.0 ((((';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
  it('registers the configured renderer scheme as privileged before app ready', () => {
  createClerkBridge({
  storage,

packages/electron/src/main/create-clerk-bridge.ts

@@ -1,4 +1,4 @@
-import { protocol } from 'electron';
+import { app, protocol } from 'electron';
 
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
@@ -19,6 +19,21 @@ function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridge
  }
 }
 
+function buildUserAgentFallback(defaultUserAgent: string, productToken: string): string {
+ const platformCommentStart = defaultUserAgent.indexOf('(');
+ const platformCommentEnd = defaultUserAgent.indexOf(')', platformCommentStart + 1);
+
+ if (platformCommentStart === -1 || platformCommentEnd === -1) {
+ return productToken;
+ }
+
+ const platformComment = defaultUserAgent.slice(platformCommentStart, platformCommentEnd + 1);
+
+ // Clerk's session activity parser preserves the platform comment and treats the
+ // token after Gecko as the app/browser name.
+ return `Mozilla/5.0 ${platformComment} Gecko/20100101 ${productToken}`;
+}
+
 /**
  * Creates the Clerk bridge for Electron's main process.
  *
@@ -37,6 +52,10 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
  let cleanupOAuthTransport: (() => void) | undefined;
  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
+ if (options.userAgent) {
+ app.userAgentFallback = buildUserAgentFallback(app.userAgentFallback, options.userAgent);
+ }
+
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
 

packages/electron/src/shared/types.ts

@@ -22,6 +22,13 @@ export type CreateClerkBridgeOptions = {
  * the optional `@clerk/electron-passkeys` package and `exposeClerkBridge({ passkeys: true })`.
  */
  passkeys?: boolean;
+ /**
+ * Product token to use in Electron's user-agent fallback. Clerk uses the resulting
+ * user-agent for UserProfile session activity attribution when no webContents or
+ * session-level user-agent is set. The Electron platform comment is preserved so
+ * device details such as macOS or Windows can still be detected.
+ */
+ userAgent?: string;
 };
 
 export type ExposeClerkBridgeOptions = {

.changeset/electron-user-agent.md

@@ -0,0 +1,5 @@
+---
+"@clerk/electron": patch
+---
+
+Add a `userAgent` option to `createClerkBridge()` so Electron apps can customize the app name used for UserProfile session activity attribution while preserving platform details.

packages/electron/README.md

@@ -96,6 +96,16 @@ import { passkeys } from '@clerk/electron/passkeys';
 </ClerkProvider>;
 ```
 
+Pass `userAgent` to `createClerkBridge` before creating renderer windows to set an app-specific product token, such as `Acme Co/1.0.0`. Clerk preserves Electron's platform details, such as `Macintosh` or `Windows`, while using the product token for UserProfile session activity attribution:
+
+```ts
+createClerkBridge({
+ storage: storage(),
+ renderer: { scheme: 'my-app', host: 'renderer' },
+ userAgent: 'Acme Co/1.0.0',
+});
+```
+
 ## Content Security Policy
 
 `@clerk/electron` loads Clerk's prebuilt UI from Clerk's CDN at runtime rather than bundling it, so your renderer's Content Security Policy must allow Clerk's Frontend API host. If it doesn't, the UI script fails to load and Clerk components never render.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -10,6 +10,8 @@ vi.mock('electron', () => ({
  on: vi.fn(),
  removeListener: vi.fn(),
  setAsDefaultProtocolClient: vi.fn(),
+ userAgentFallback:
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  },
  ipcMain: {
  handle: vi.fn(),
@@ -42,6 +44,8 @@ describe('createClerkBridge', () => {
 
  beforeEach(() => {
  vi.clearAllMocks();
+ app.userAgentFallback =
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
  });
 
  it('requires a storage adapter', () => {
@@ -54,6 +58,28 @@ describe('createClerkBridge', () => {
  expect(ipcMain.handle).toHaveBeenCalledTimes(3);
  });
 
+ it('keeps the platform details when setting the app user-agent fallback', () => {
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has no platform details', () => {
+ app.userAgentFallback = 'Electron default';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has malformed platform details', () => {
+ app.userAgentFallback = 'Mozilla/5.0 ((((';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
  it('registers the configured renderer scheme as privileged before app ready', () => {
  createClerkBridge({
  storage,

packages/electron/src/main/create-clerk-bridge.ts

@@ -1,4 +1,4 @@
-import { protocol } from 'electron';
+import { app, protocol } from 'electron';
 
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
@@ -19,6 +19,21 @@ function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridge
  }
 }
 
+function buildUserAgentFallback(defaultUserAgent: string, productToken: string): string {
+ const platformCommentStart = defaultUserAgent.indexOf('(');
+ const platformCommentEnd = defaultUserAgent.indexOf(')', platformCommentStart + 1);
+
+ if (platformCommentStart === -1 || platformCommentEnd === -1) {
+ return productToken;
+ }
+
+ const platformComment = defaultUserAgent.slice(platformCommentStart, platformCommentEnd + 1);
+
+ // Clerk's session activity parser preserves the platform comment and treats the
+ // token after Gecko as the app/browser name.
+ return `Mozilla/5.0 ${platformComment} Gecko/20100101 ${productToken}`;
+}
+
 /**
  * Creates the Clerk bridge for Electron's main process.
  *
@@ -37,6 +52,10 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
  let cleanupOAuthTransport: (() => void) | undefined;
  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
+ if (options.userAgent) {
+ app.userAgentFallback = buildUserAgentFallback(app.userAgentFallback, options.userAgent);
+ }
+
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
 

packages/electron/src/shared/types.ts

@@ -22,6 +22,13 @@ export type CreateClerkBridgeOptions = {
  * the optional `@clerk/electron-passkeys` package and `exposeClerkBridge({ passkeys: true })`.
  */
  passkeys?: boolean;
+ /**
+ * Product token to use in Electron's user-agent fallback. Clerk uses the resulting
+ * user-agent for UserProfile session activity attribution when no webContents or
+ * session-level user-agent is set. The Electron platform comment is preserved so
+ * device details such as macOS or Windows can still be detected.
+ */
+ userAgent?: string;
 };
 
 export type ExposeClerkBridgeOptions = {

.changeset/electron-user-agent.md

@@ -0,0 +1,5 @@
+---
+"@clerk/electron": patch
+---
+
+Add a `userAgent` option to `createClerkBridge()` so Electron apps can customize the app name used for UserProfile session activity attribution while preserving platform details.

packages/electron/README.md

@@ -96,6 +96,16 @@ import { passkeys } from '@clerk/electron/passkeys';
 </ClerkProvider>;
 ```
 
+Pass `userAgent` to `createClerkBridge` before creating renderer windows to set an app-specific product token, such as `Acme Co/1.0.0`. Clerk preserves Electron's platform details, such as `Macintosh` or `Windows`, while using the product token for UserProfile session activity attribution:
+
+```ts
+createClerkBridge({
+ storage: storage(),
+ renderer: { scheme: 'my-app', host: 'renderer' },
+ userAgent: 'Acme Co/1.0.0',
+});
+```
+
 ## Content Security Policy
 
 `@clerk/electron` loads Clerk's prebuilt UI from Clerk's CDN at runtime rather than bundling it, so your renderer's Content Security Policy must allow Clerk's Frontend API host. If it doesn't, the UI script fails to load and Clerk components never render.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -10,6 +10,8 @@ vi.mock('electron', () => ({
  on: vi.fn(),
  removeListener: vi.fn(),
  setAsDefaultProtocolClient: vi.fn(),
+ userAgentFallback:
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  },
  ipcMain: {
  handle: vi.fn(),
@@ -42,6 +44,8 @@ describe('createClerkBridge', () => {
 
  beforeEach(() => {
  vi.clearAllMocks();
+ app.userAgentFallback =
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
  });
 
  it('requires a storage adapter', () => {
@@ -54,6 +58,28 @@ describe('createClerkBridge', () => {
  expect(ipcMain.handle).toHaveBeenCalledTimes(3);
  });
 
+ it('keeps the platform details when setting the app user-agent fallback', () => {
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has no platform details', () => {
+ app.userAgentFallback = 'Electron default';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has malformed platform details', () => {
+ app.userAgentFallback = 'Mozilla/5.0 ((((';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
  it('registers the configured renderer scheme as privileged before app ready', () => {
  createClerkBridge({
  storage,

packages/electron/src/main/create-clerk-bridge.ts

@@ -1,4 +1,4 @@
-import { protocol } from 'electron';
+import { app, protocol } from 'electron';
 
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
@@ -19,6 +19,21 @@ function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridge
  }
 }
 
+function buildUserAgentFallback(defaultUserAgent: string, productToken: string): string {
+ const platformCommentStart = defaultUserAgent.indexOf('(');
+ const platformCommentEnd = defaultUserAgent.indexOf(')', platformCommentStart + 1);
+
+ if (platformCommentStart === -1 || platformCommentEnd === -1) {
+ return productToken;
+ }
+
+ const platformComment = defaultUserAgent.slice(platformCommentStart, platformCommentEnd + 1);
+
+ // Clerk's session activity parser preserves the platform comment and treats the
+ // token after Gecko as the app/browser name.
+ return `Mozilla/5.0 ${platformComment} Gecko/20100101 ${productToken}`;
+}
+
 /**
  * Creates the Clerk bridge for Electron's main process.
  *
@@ -37,6 +52,10 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
  let cleanupOAuthTransport: (() => void) | undefined;
  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
+ if (options.userAgent) {
+ app.userAgentFallback = buildUserAgentFallback(app.userAgentFallback, options.userAgent);
+ }
+
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
 

packages/electron/src/shared/types.ts

@@ -22,6 +22,13 @@ export type CreateClerkBridgeOptions = {
  * the optional `@clerk/electron-passkeys` package and `exposeClerkBridge({ passkeys: true })`.
  */
  passkeys?: boolean;
+ /**
+ * Product token to use in Electron's user-agent fallback. Clerk uses the resulting
+ * user-agent for UserProfile session activity attribution when no webContents or
+ * session-level user-agent is set. The Electron platform comment is preserved so
+ * device details such as macOS or Windows can still be detected.
+ */
+ userAgent?: string;
 };
 
 export type ExposeClerkBridgeOptions = {

.changeset/electron-user-agent.md

@@ -0,0 +1,5 @@
+---
+"@clerk/electron": patch
+---
+
+Add a `userAgent` option to `createClerkBridge()` so Electron apps can customize the app name used for UserProfile session activity attribution while preserving platform details.

packages/electron/README.md

@@ -96,6 +96,16 @@ import { passkeys } from '@clerk/electron/passkeys';
 </ClerkProvider>;
 ```
 
+Pass `userAgent` to `createClerkBridge` before creating renderer windows to set an app-specific product token, such as `Acme Co/1.0.0`. Clerk preserves Electron's platform details, such as `Macintosh` or `Windows`, while using the product token for UserProfile session activity attribution:
+
+```ts
+createClerkBridge({
+ storage: storage(),
+ renderer: { scheme: 'my-app', host: 'renderer' },
+ userAgent: 'Acme Co/1.0.0',
+});
+```
+
 ## Content Security Policy
 
 `@clerk/electron` loads Clerk's prebuilt UI from Clerk's CDN at runtime rather than bundling it, so your renderer's Content Security Policy must allow Clerk's Frontend API host. If it doesn't, the UI script fails to load and Clerk components never render.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -10,6 +10,8 @@ vi.mock('electron', () => ({
  on: vi.fn(),
  removeListener: vi.fn(),
  setAsDefaultProtocolClient: vi.fn(),
+ userAgentFallback:
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  },
  ipcMain: {
  handle: vi.fn(),
@@ -42,6 +44,8 @@ describe('createClerkBridge', () => {
 
  beforeEach(() => {
  vi.clearAllMocks();
+ app.userAgentFallback =
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
  });
 
  it('requires a storage adapter', () => {
@@ -54,6 +58,28 @@ describe('createClerkBridge', () => {
  expect(ipcMain.handle).toHaveBeenCalledTimes(3);
  });
 
+ it('keeps the platform details when setting the app user-agent fallback', () => {
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has no platform details', () => {
+ app.userAgentFallback = 'Electron default';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has malformed platform details', () => {
+ app.userAgentFallback = 'Mozilla/5.0 ((((';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
  it('registers the configured renderer scheme as privileged before app ready', () => {
  createClerkBridge({
  storage,

packages/electron/src/main/create-clerk-bridge.ts

@@ -1,4 +1,4 @@
-import { protocol } from 'electron';
+import { app, protocol } from 'electron';
 
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
@@ -19,6 +19,21 @@ function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridge
  }
 }
 
+function buildUserAgentFallback(defaultUserAgent: string, productToken: string): string {
+ const platformCommentStart = defaultUserAgent.indexOf('(');
+ const platformCommentEnd = defaultUserAgent.indexOf(')', platformCommentStart + 1);
+
+ if (platformCommentStart === -1 || platformCommentEnd === -1) {
+ return productToken;
+ }
+
+ const platformComment = defaultUserAgent.slice(platformCommentStart, platformCommentEnd + 1);
+
+ // Clerk's session activity parser preserves the platform comment and treats the
+ // token after Gecko as the app/browser name.
+ return `Mozilla/5.0 ${platformComment} Gecko/20100101 ${productToken}`;
+}
+
 /**
  * Creates the Clerk bridge for Electron's main process.
  *
@@ -37,6 +52,10 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
  let cleanupOAuthTransport: (() => void) | undefined;
  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
+ if (options.userAgent) {
+ app.userAgentFallback = buildUserAgentFallback(app.userAgentFallback, options.userAgent);
+ }
+
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
 

packages/electron/src/shared/types.ts

@@ -22,6 +22,13 @@ export type CreateClerkBridgeOptions = {
  * the optional `@clerk/electron-passkeys` package and `exposeClerkBridge({ passkeys: true })`.
  */
  passkeys?: boolean;
+ /**
+ * Product token to use in Electron's user-agent fallback. Clerk uses the resulting
+ * user-agent for UserProfile session activity attribution when no webContents or
+ * session-level user-agent is set. The Electron platform comment is preserved so
+ * device details such as macOS or Windows can still be detected.
+ */
+ userAgent?: string;
 };
 
 export type ExposeClerkBridgeOptions = {

.changeset/electron-user-agent.md

@@ -0,0 +1,5 @@
+---
+"@clerk/electron": patch
+---
+
+Add a `userAgent` option to `createClerkBridge()` so Electron apps can customize the app name used for UserProfile session activity attribution while preserving platform details.

packages/electron/README.md

@@ -96,6 +96,16 @@ import { passkeys } from '@clerk/electron/passkeys';
 </ClerkProvider>;
 ```
 
+Pass `userAgent` to `createClerkBridge` before creating renderer windows to set an app-specific product token, such as `Acme Co/1.0.0`. Clerk preserves Electron's platform details, such as `Macintosh` or `Windows`, while using the product token for UserProfile session activity attribution:
+
+```ts
+createClerkBridge({
+ storage: storage(),
+ renderer: { scheme: 'my-app', host: 'renderer' },
+ userAgent: 'Acme Co/1.0.0',
+});
+```
+
 ## Content Security Policy
 
 `@clerk/electron` loads Clerk's prebuilt UI from Clerk's CDN at runtime rather than bundling it, so your renderer's Content Security Policy must allow Clerk's Frontend API host. If it doesn't, the UI script fails to load and Clerk components never render.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -10,6 +10,8 @@ vi.mock('electron', () => ({
  on: vi.fn(),
  removeListener: vi.fn(),
  setAsDefaultProtocolClient: vi.fn(),
+ userAgentFallback:
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  },
  ipcMain: {
  handle: vi.fn(),
@@ -42,6 +44,8 @@ describe('createClerkBridge', () => {
 
  beforeEach(() => {
  vi.clearAllMocks();
+ app.userAgentFallback =
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
  });
 
  it('requires a storage adapter', () => {
@@ -54,6 +58,28 @@ describe('createClerkBridge', () => {
  expect(ipcMain.handle).toHaveBeenCalledTimes(3);
  });
 
+ it('keeps the platform details when setting the app user-agent fallback', () => {
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has no platform details', () => {
+ app.userAgentFallback = 'Electron default';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has malformed platform details', () => {
+ app.userAgentFallback = 'Mozilla/5.0 ((((';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
  it('registers the configured renderer scheme as privileged before app ready', () => {
  createClerkBridge({
  storage,

packages/electron/src/main/create-clerk-bridge.ts

@@ -1,4 +1,4 @@
-import { protocol } from 'electron';
+import { app, protocol } from 'electron';
 
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
@@ -19,6 +19,21 @@ function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridge
  }
 }
 
+function buildUserAgentFallback(defaultUserAgent: string, productToken: string): string {
+ const platformCommentStart = defaultUserAgent.indexOf('(');
+ const platformCommentEnd = defaultUserAgent.indexOf(')', platformCommentStart + 1);
+
+ if (platformCommentStart === -1 || platformCommentEnd === -1) {
+ return productToken;
+ }
+
+ const platformComment = defaultUserAgent.slice(platformCommentStart, platformCommentEnd + 1);
+
+ // Clerk's session activity parser preserves the platform comment and treats the
+ // token after Gecko as the app/browser name.
+ return `Mozilla/5.0 ${platformComment} Gecko/20100101 ${productToken}`;
+}
+
 /**
  * Creates the Clerk bridge for Electron's main process.
  *
@@ -37,6 +52,10 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
  let cleanupOAuthTransport: (() => void) | undefined;
  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
+ if (options.userAgent) {
+ app.userAgentFallback = buildUserAgentFallback(app.userAgentFallback, options.userAgent);
+ }
+
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
 

packages/electron/src/shared/types.ts

@@ -22,6 +22,13 @@ export type CreateClerkBridgeOptions = {
  * the optional `@clerk/electron-passkeys` package and `exposeClerkBridge({ passkeys: true })`.
  */
  passkeys?: boolean;
+ /**
+ * Product token to use in Electron's user-agent fallback. Clerk uses the resulting
+ * user-agent for UserProfile session activity attribution when no webContents or
+ * session-level user-agent is set. The Electron platform comment is preserved so
+ * device details such as macOS or Windows can still be detected.
+ */
+ userAgent?: string;
 };
 
 export type ExposeClerkBridgeOptions = {

.changeset/electron-user-agent.md

@@ -0,0 +1,5 @@
+---
+"@clerk/electron": patch
+---
+
+Add a `userAgent` option to `createClerkBridge()` so Electron apps can customize the app name used for UserProfile session activity attribution while preserving platform details.

packages/electron/README.md

@@ -96,6 +96,16 @@ import { passkeys } from '@clerk/electron/passkeys';
 </ClerkProvider>;
 ```
 
+Pass `userAgent` to `createClerkBridge` before creating renderer windows to set an app-specific product token, such as `Acme Co/1.0.0`. Clerk preserves Electron's platform details, such as `Macintosh` or `Windows`, while using the product token for UserProfile session activity attribution:
+
+```ts
+createClerkBridge({
+ storage: storage(),
+ renderer: { scheme: 'my-app', host: 'renderer' },
+ userAgent: 'Acme Co/1.0.0',
+});
+```
+
 ## Content Security Policy
 
 `@clerk/electron` loads Clerk's prebuilt UI from Clerk's CDN at runtime rather than bundling it, so your renderer's Content Security Policy must allow Clerk's Frontend API host. If it doesn't, the UI script fails to load and Clerk components never render.

packages/electron/src/main/__tests__/create-clerk-bridge.test.ts

@@ -10,6 +10,8 @@ vi.mock('electron', () => ({
  on: vi.fn(),
  removeListener: vi.fn(),
  setAsDefaultProtocolClient: vi.fn(),
+ userAgentFallback:
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  },
  ipcMain: {
  handle: vi.fn(),
@@ -42,6 +44,8 @@ describe('createClerkBridge', () => {
 
  beforeEach(() => {
  vi.clearAllMocks();
+ app.userAgentFallback =
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
  });
 
  it('requires a storage adapter', () => {
@@ -54,6 +58,28 @@ describe('createClerkBridge', () => {
  expect(ipcMain.handle).toHaveBeenCalledTimes(3);
  });
 
+ it('keeps the platform details when setting the app user-agent fallback', () => {
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has no platform details', () => {
+ app.userAgentFallback = 'Electron default';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
+ it('falls back to the configured user-agent when the app fallback has malformed platform details', () => {
+ app.userAgentFallback = 'Mozilla/5.0 ((((';
+
+ createClerkBridge({ storage, userAgent: 'Acme Co/1.0.0' });
+
+ expect(app.userAgentFallback).toBe('Acme Co/1.0.0');
+ });
+
  it('registers the configured renderer scheme as privileged before app ready', () => {
  createClerkBridge({
  storage,

packages/electron/src/main/create-clerk-bridge.ts

@@ -1,4 +1,4 @@
-import { protocol } from 'electron';
+import { app, protocol } from 'electron';
 
 import type { ClerkBridge, CreateClerkBridgeOptions } from '../shared/types';
 import { setupTokenCacheIpcHandlers } from './ipc-handlers';
@@ -19,6 +19,21 @@ function assertValidRendererOriginConfig(renderer: NonNullable<CreateClerkBridge
  }
 }
 
+function buildUserAgentFallback(defaultUserAgent: string, productToken: string): string {
+ const platformCommentStart = defaultUserAgent.indexOf('(');
+ const platformCommentEnd = defaultUserAgent.indexOf(')', platformCommentStart + 1);
+
+ if (platformCommentStart === -1 || platformCommentEnd === -1) {
+ return productToken;
+ }
+
+ const platformComment = defaultUserAgent.slice(platformCommentStart, platformCommentEnd + 1);
+
+ // Clerk's session activity parser preserves the platform comment and treats the
+ // token after Gecko as the app/browser name.
+ return `Mozilla/5.0 ${platformComment} Gecko/20100101 ${productToken}`;
+}
+
 /**
  * Creates the Clerk bridge for Electron's main process.
  *
@@ -37,6 +52,10 @@ export function createClerkBridge(options: CreateClerkBridgeOptions): ClerkBridg
  let cleanupOAuthTransport: (() => void) | undefined;
  const passkeys = options.passkeys ? setupPasskeysMain() : null;
 
+ if (options.userAgent) {
+ app.userAgentFallback = buildUserAgentFallback(app.userAgentFallback, options.userAgent);
+ }
+
  if (options.renderer) {
  assertValidRendererOriginConfig(options.renderer);
 

packages/electron/src/shared/types.ts

@@ -22,6 +22,13 @@ export type CreateClerkBridgeOptions = {
  * the optional `@clerk/electron-passkeys` package and `exposeClerkBridge({ passkeys: true })`.
  */
  passkeys?: boolean;
+ /**
+ * Product token to use in Electron's user-agent fallback. Clerk uses the resulting
+ * user-agent for UserProfile session activity attribution when no webContents or
+ * session-level user-agent is set. The Electron platform comment is preserved so
+ * device details such as macOS or Windows can still be detected.
+ */
+ userAgent?: string;
 };
 
 export type ExposeClerkBridgeOptions = {