feat(passport): ID-3960 Headless login analytics (#2706)

Author: haydenfowler

packages/game-bridge/src/index.ts

@@ -362,7 +362,8 @@ window.callFunction = async (jsonData: string) => {
       case PASSPORT_FUNCTIONS.getPKCEAuthUrl: {
         const request = data ? JSON.parse(data) : {};
         const directLoginOptions: passport.DirectLoginOptions | undefined = request?.directLoginOptions;
-        const url = await getPassportClient().loginWithPKCEFlow(directLoginOptions);
+        const imPassportTraceId: string | undefined = request?.imPassportTraceId;
+        const url = await getPassportClient().loginWithPKCEFlow(directLoginOptions, imPassportTraceId);
         trackDuration(moduleName, 'performedGetPkceAuthUrl', mt(markStart));
         callbackToGame({
           responseFor: fxName,

packages/passport/sdk/src/Passport.ts

@@ -266,11 +266,12 @@ export class Passport {
   /**
    * Initiates a PKCE flow login.
    * @param {DirectLoginOptions} [directLoginOptions] - If provided, directly redirects to the specified login method
+   * @param {string} [imPassportTraceId] - The trace ID for the PKCE flow
    * @returns {string} The authorization URL for the PKCE flow
    */
-  public loginWithPKCEFlow(directLoginOptions?: DirectLoginOptions): Promise<string> {
+  public loginWithPKCEFlow(directLoginOptions?: DirectLoginOptions, imPassportTraceId?: string): Promise<string> {
     return withMetricsAsync(
-      async () => await this.authManager.getPKCEAuthorizationUrl(directLoginOptions),
+      async () => await this.authManager.getPKCEAuthorizationUrl(directLoginOptions, imPassportTraceId),
       'loginWithPKCEFlow',
     );
   }

packages/passport/sdk/src/authManager.test.ts

@@ -415,6 +415,14 @@ describe('AuthManager', () => {
         });
         const am = new AuthManager(configWithPopupOverlayOptions, mockEmbeddedLoginPrompt);
 
+        // Mock the embedded login prompt to return a result
+        const mockEmbeddedLoginPromptResult = {
+          directLoginMethod: 'google' as const,
+          marketingConsentStatus: MarketingConsentStatus.OptedIn,
+          imPassportTraceId: 'test-trace-id',
+        };
+        mockEmbeddedLoginPrompt.displayEmbeddedLoginPrompt.mockResolvedValue(mockEmbeddedLoginPromptResult);
+
         mockSigninPopup.mockReturnValue(mockOidcUser);
         // Simulate `tryAgainOnClick` being called so that the `login()` promise can resolve
         mockOverlayAppend.mockImplementation(async (tryAgainOnClick: () => Promise<void>) => {
@@ -1080,6 +1088,13 @@ describe('AuthManager', () => {
       expect(url.searchParams.get('marketingConsent')).toEqual(MarketingConsentStatus.OptedIn);
       expect(url.searchParams.get('audience')).toEqual('test-audience');
     });
+
+    it('should include im_passport_trace_id parameter when imPassportTraceId is provided', async () => {
+      const result = await authManager.getPKCEAuthorizationUrl(undefined, 'test-trace-id');
+      const url = new URL(result);
+
+      expect(url.searchParams.get('im_passport_trace_id')).toEqual('test-trace-id');
+    });
   });
 
   describe('login with directLoginMethod', () => {
@@ -1178,8 +1193,12 @@ describe('AuthManager', () => {
     });
 
     it('should call displayEmbeddedLoginPrompt when no directLoginOptions provided and overlay is enabled', async () => {
-      const mockDirectLoginOptions = { directLoginMethod: 'google' as const };
-      mockEmbeddedLoginPrompt.displayEmbeddedLoginPrompt.mockResolvedValue(mockDirectLoginOptions);
+      const mockEmbeddedLoginPromptResult = {
+        directLoginMethod: 'google' as const,
+        marketingConsentStatus: MarketingConsentStatus.OptedIn,
+        imPassportTraceId: 'test-trace-id',
+      };
+      mockEmbeddedLoginPrompt.displayEmbeddedLoginPrompt.mockResolvedValue(mockEmbeddedLoginPromptResult);
       mockSigninPopup.mockResolvedValue(mockOidcUser);
 
       await authManager.login();
@@ -1190,6 +1209,8 @@ describe('AuthManager', () => {
           rid: '',
           third_party_a_id: '',
           direct: 'google',
+          marketingConsent: MarketingConsentStatus.OptedIn,
+          im_passport_trace_id: 'test-trace-id',
         },
         popupWindowFeatures: {
           width: 410,
@@ -1234,12 +1255,13 @@ describe('AuthManager', () => {
     });
 
     it('should handle email login method from embedded prompt', async () => {
-      const mockDirectLoginOptions = {
+      const mockEmbeddedLoginPromptResult = {
         directLoginMethod: 'email' as const,
         email: '[email protected]',
         marketingConsentStatus: MarketingConsentStatus.OptedIn,
+        imPassportTraceId: 'test-trace-id-email',
       };
-      mockEmbeddedLoginPrompt.displayEmbeddedLoginPrompt.mockResolvedValue(mockDirectLoginOptions);
+      mockEmbeddedLoginPrompt.displayEmbeddedLoginPrompt.mockResolvedValue(mockEmbeddedLoginPromptResult);
       mockSigninPopup.mockResolvedValue(mockOidcUser);
 
       await authManager.login('anonymous-id');
@@ -1252,6 +1274,7 @@ describe('AuthManager', () => {
           direct: 'email',
           email: '[email protected]',
           marketingConsent: MarketingConsentStatus.OptedIn,
+          im_passport_trace_id: 'test-trace-id-email',
         },
         popupWindowFeatures: {
           width: 410,

packages/passport/sdk/src/authManager.ts

@@ -183,7 +183,11 @@ export default class AuthManager {
     });
   };
 
-  private buildExtraQueryParams(anonymousId?: string, directLoginOptions?: DirectLoginOptions): Record<string, string> {
+  private buildExtraQueryParams(
+    anonymousId?: string,
+    directLoginOptions?: DirectLoginOptions,
+    imPassportTraceId?: string,
+  ): Record<string, string> {
     const params: Record<string, string> = {
       ...(this.userManager.settings?.extraQueryParams ?? {}),
       rid: getDetail(Detail.RUNTIME_ID) || '',
@@ -208,6 +212,10 @@ export default class AuthManager {
       }
     }
 
+    if (imPassportTraceId) {
+      params.im_passport_trace_id = imPassportTraceId;
+    }
+
     return params;
   }
 
@@ -232,16 +240,24 @@ export default class AuthManager {
    */
   public async login(anonymousId?: string, directLoginOptions?: DirectLoginOptions): Promise<User> {
     return withPassportError<User>(async () => {
+      // If directLoginOptions are provided, then the consumer has rendered their own initial login screen.
+      // If not, display the embedded login prompt and pass the returned direct login options and imPassportTraceId to the login popup.
       let directLoginOptionsToUse: DirectLoginOptions | undefined;
+      let imPassportTraceId: string | undefined;
       if (directLoginOptions) {
         directLoginOptionsToUse = directLoginOptions;
       } else if (!this.config.popupOverlayOptions.disableHeadlessLoginPromptOverlay) {
-        directLoginOptionsToUse = await this.embeddedLoginPrompt.displayEmbeddedLoginPrompt();
+        const {
+          imPassportTraceId: embeddedLoginPromptImPassportTraceId,
+          ...embeddedLoginPromptDirectLoginOptions
+        } = await this.embeddedLoginPrompt.displayEmbeddedLoginPrompt();
+        directLoginOptionsToUse = embeddedLoginPromptDirectLoginOptions;
+        imPassportTraceId = embeddedLoginPromptImPassportTraceId;
       }
 
       const popupWindowTarget = window.crypto.randomUUID();
       const signinPopup = async () => {
-        const extraQueryParams = this.buildExtraQueryParams(anonymousId, directLoginOptionsToUse);
+        const extraQueryParams = this.buildExtraQueryParams(anonymousId, directLoginOptionsToUse, imPassportTraceId);
 
         const userPromise = this.userManager.signinPopup({
           extraQueryParams,
@@ -380,7 +396,10 @@ export default class AuthManager {
     }, PassportErrorType.AUTHENTICATION_ERROR);
   }
 
-  public async getPKCEAuthorizationUrl(directLoginOptions?: DirectLoginOptions): Promise<string> {
+  public async getPKCEAuthorizationUrl(
+    directLoginOptions?: DirectLoginOptions,
+    imPassportTraceId?: string,
+  ): Promise<string> {
     const verifier = base64URLEncode(window.crypto.getRandomValues(new Uint8Array(32)));
     const challenge = base64URLEncode(await sha256(verifier));
 
@@ -421,6 +440,10 @@ export default class AuthManager {
       }
     }
 
+    if (imPassportTraceId) {
+      pKCEAuthorizationUrl.searchParams.set('im_passport_trace_id', imPassportTraceId);
+    }
+
     return pKCEAuthorizationUrl.toString();
   }
 

packages/passport/sdk/src/confirmation/embeddedLoginPrompt.test.ts

@@ -6,7 +6,7 @@ import {
   EmbeddedLoginPromptReceiveMessage,
   EmbeddedLoginPromptResult,
 } from './types';
-import { DirectLoginOptions, MarketingConsentStatus } from '../types';
+import { MarketingConsentStatus } from '../types';
 
 // Mock dependencies
 jest.mock('../overlay/embeddedLoginPromptOverlay');
@@ -63,7 +63,7 @@ describe('EmbeddedLoginPrompt', () => {
   describe('getHref', () => {
     it('should generate correct href with client ID', () => {
       const href = (embeddedLoginPrompt as any).getHref();
-      expect(href).toBe(`https://auth.immutable.com/im-embedded-login-prompt?client_id=${mockClientId}`);
+      expect(href).toBe(`https://auth.immutable.com/im-embedded-login-prompt?client_id=${mockClientId}&rid=undefined`);
     });
   });
 
@@ -160,6 +160,7 @@ describe('EmbeddedLoginPrompt', () => {
         directLoginMethod: 'email',
         email: '[email protected]',
         marketingConsentStatus: MarketingConsentStatus.OptedIn,
+        imPassportTraceId: 'test-im-passport-trace-id',
       };
 
       const promise = embeddedLoginPrompt.displayEmbeddedLoginPrompt();
@@ -178,10 +179,11 @@ describe('EmbeddedLoginPrompt', () => {
       messageHandler(mockEvent);
 
       const result = await promise;
-      const expectedResult: DirectLoginOptions = {
+      const expectedResult: EmbeddedLoginPromptResult = {
         directLoginMethod: 'email',
         marketingConsentStatus: MarketingConsentStatus.OptedIn,
         email: '[email protected]',
+        imPassportTraceId: 'test-im-passport-trace-id',
       };
 
       expect(result).toEqual(expectedResult);
@@ -193,6 +195,7 @@ describe('EmbeddedLoginPrompt', () => {
       const mockLoginResult: EmbeddedLoginPromptResult = {
         directLoginMethod: 'google',
         marketingConsentStatus: MarketingConsentStatus.Unsubscribed,
+        imPassportTraceId: 'test-im-passport-trace-id',
       };
 
       const promise = embeddedLoginPrompt.displayEmbeddedLoginPrompt();
@@ -211,9 +214,10 @@ describe('EmbeddedLoginPrompt', () => {
       messageHandler(mockEvent);
 
       const result = await promise;
-      const expectedResult: DirectLoginOptions = {
+      const expectedResult: EmbeddedLoginPromptResult = {
         directLoginMethod: 'google',
         marketingConsentStatus: MarketingConsentStatus.Unsubscribed,
+        imPassportTraceId: 'test-im-passport-trace-id',
       };
 
       expect(result).toEqual(expectedResult);
@@ -276,7 +280,7 @@ describe('EmbeddedLoginPrompt', () => {
 
       messageHandler(mockEvent);
 
-      await expect(promise).rejects.toThrow('Unsupported message type');
+      await expect(promise).rejects.toThrow('Unsupported message type: UNKNOWN_MESSAGE_TYPE');
       expect(mockRemoveEventListener).toHaveBeenCalledWith('message', messageHandler);
       expect(mockOverlay.remove).toHaveBeenCalled();
     });

packages/passport/sdk/src/confirmation/embeddedLoginPrompt.ts

@@ -1,11 +1,11 @@
+import { Detail, getDetail } from '@imtbl/metrics';
 import {
   EMBEDDED_LOGIN_PROMPT_EVENT_TYPE,
   EmbeddedLoginPromptResult,
   EmbeddedLoginPromptReceiveMessage,
 } from './types';
 import { PassportConfiguration } from '../config';
 import EmbeddedLoginPromptOverlay from '../overlay/embeddedLoginPromptOverlay';
-import { DirectLoginOptions } from '../types';
 
 const LOGIN_PROMPT_WINDOW_HEIGHT = 560;
 const LOGIN_PROMPT_WINDOW_WIDTH = 440;
@@ -21,7 +21,9 @@ export default class EmbeddedLoginPrompt {
   }
 
   private getHref = () => (
-    `${this.config.authenticationDomain}/im-embedded-login-prompt?client_id=${this.config.oidcConfiguration.clientId}`
+    `${this.config.authenticationDomain}/im-embedded-login-prompt`
+    + `?client_id=${this.config.oidcConfiguration.clientId}`
+    + `&rid=${getDetail(Detail.RUNTIME_ID)}`
   );
 
   private static appendIFrameStylesIfNeeded = () => {
@@ -89,7 +91,7 @@ export default class EmbeddedLoginPrompt {
     return embeddedLoginPrompt;
   };
 
-  public displayEmbeddedLoginPrompt(): Promise<DirectLoginOptions> {
+  public displayEmbeddedLoginPrompt(): Promise<EmbeddedLoginPromptResult> {
     return new Promise((resolve, reject) => {
       const embeddedLoginPrompt = this.getEmbeddedLoginIFrame();
       const messageHandler = ({ data, origin }: MessageEvent) => {
@@ -102,20 +104,7 @@ export default class EmbeddedLoginPrompt {
 
         switch (data.messageType as EmbeddedLoginPromptReceiveMessage) {
           case EmbeddedLoginPromptReceiveMessage.LOGIN_METHOD_SELECTED: {
-            const loginMethod = data.payload as EmbeddedLoginPromptResult;
-            let result: DirectLoginOptions;
-            if (loginMethod.directLoginMethod === 'email') {
-              result = {
-                directLoginMethod: 'email',
-                marketingConsentStatus: loginMethod.marketingConsentStatus,
-                email: loginMethod.email,
-              };
-            } else {
-              result = {
-                directLoginMethod: loginMethod.directLoginMethod,
-                marketingConsentStatus: loginMethod.marketingConsentStatus,
-              };
-            }
+            const result = data.payload as EmbeddedLoginPromptResult;
             window.removeEventListener('message', messageHandler);
             EmbeddedLoginPromptOverlay.remove();
             resolve(result);
@@ -136,7 +125,7 @@ export default class EmbeddedLoginPrompt {
           default:
             window.removeEventListener('message', messageHandler);
             EmbeddedLoginPromptOverlay.remove();
-            reject(new Error('Unsupported message type'));
+            reject(new Error(`Unsupported message type: ${data.messageType}`));
             break;
         }
       };

packages/passport/sdk/src/confirmation/types.ts

@@ -26,6 +26,7 @@ export type ConfirmationResult = {
 
 export type EmbeddedLoginPromptResult = {
   marketingConsentStatus: MarketingConsentStatus;
+  imPassportTraceId: string;
 } & (
   | { directLoginMethod: 'email'; email: string }
   | { directLoginMethod: Exclude<DirectLoginMethod, 'email'>; email?: never }

packages/passport/sdk/src/overlay/elements.ts

@@ -133,28 +133,28 @@ export const getEmbeddedLoginPromptOverlay = (): string => `
     <div
       id="${PASSPORT_OVERLAY_ID}"
       style="
-        position: fixed !important;
-        top: 0 !important;
-        left: 0 !important;
-        width: 100% !important;
-        height: 100% !important;
-        display: flex !important;
-        flex-direction: column !important;
-        justify-content: center !important;
-        align-items: center !important;
-        z-index: 2147483647 !important;
-        background: rgba(247, 247, 247, 0.24) !important;
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+        z-index: 2147483647;
+        background: rgba(247, 247, 247, 0.24);
         animation-name: passportEmbeddedLoginPromptOverlayFadeIn;
         animation-duration: 0.8s;
       "
     >
       <div
         id="${PASSPORT_OVERLAY_CONTENTS_ID}"
         style="
-          display: flex !important;
-          flex-direction: column !important;
-          align-items: center !important;
-          width: 100% !important;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          width: 100%;
         "
       />
     </div>