diff --git a/apps/billing-web/src/checkout/checkoutJourney.ts b/apps/billing-web/src/checkout/checkoutJourney.ts index ae5e3ede733..30a6b557947 100644 --- a/apps/billing-web/src/checkout/checkoutJourney.ts +++ b/apps/billing-web/src/checkout/checkoutJourney.ts @@ -119,7 +119,7 @@ type PromoPhase = Extract export type PaymentRail = MethodSelectedPhase['rail'] export type PromoResult = PromoPhase['result'] -function methodKindOf( +export function methodKindOf( methodType: string | undefined ): MethodSelectedPhase['method_kind'] { if (methodType === undefined || methodType === '') return undefined diff --git a/apps/billing-web/src/composables/useCheckoutJourney.ts b/apps/billing-web/src/composables/useCheckoutJourney.ts index 5e085de2345..5b4c5348602 100644 --- a/apps/billing-web/src/composables/useCheckoutJourney.ts +++ b/apps/billing-web/src/composables/useCheckoutJourney.ts @@ -1,5 +1,9 @@ import type { + CheckoutEndingAttribution, + CheckoutEndingKind, CheckoutEntryFlow, + CheckoutExit, + CheckoutJourneyPhase, CheckoutJourneyPhaseEvent, PreviewSubscribeResult, SubscriptionPreview @@ -38,8 +42,15 @@ export function useCheckoutJourney(uiMode: 'embedded' | 'full_page') { let presses = 0 let linkingPress: number | undefined let billingOpId: string | undefined + let lastPhase: + | Exclude + | undefined + let lastEnding: CheckoutEndingKind | undefined + let left = false function track(phase: CheckoutJourneyPhaseEvent) { + if (phase.phase !== 'abandoned' && phase.phase !== 'ended') + lastPhase = phase.phase billingWebTelemetry.trackCheckoutJourneyEvent({ checkout_journey_id: journeyId, checkout_entered_at: enteredAt, @@ -143,9 +154,38 @@ export function useCheckoutJourney(uiMode: 'embedded' | 'full_page') { if (failed) track(failed) } + /** Once per ending screen shown; an ending resolves the journey. */ + function ended( + kind: CheckoutEndingKind, + attribution: CheckoutEndingAttribution | undefined + ) { + if (kind === lastEnding) return + lastEnding = kind + track({ + phase: 'ended', + ending_kind: kind, + ...(attribution !== undefined && { attribution }) + }) + } + + /** The checkout left its ending for a retry, so the journey is open again. */ + function resumed() { + lastEnding = undefined + } + + /** The customer left a journey no ending resolved; only the first way out counts. */ + function abandoned(exit: CheckoutExit) { + if (left || lastEnding !== undefined || lastPhase === undefined) return + left = true + track({ phase: 'abandoned', last_phase: lastPhase, exit }) + } + return { enter, track, + ended, + resumed, + abandoned, submitted, submitSettled, operationIssued, diff --git a/apps/billing-web/src/composables/useFullPageCheckout.ts b/apps/billing-web/src/composables/useFullPageCheckout.ts index 27fc97f423e..def1f860df8 100644 --- a/apps/billing-web/src/composables/useFullPageCheckout.ts +++ b/apps/billing-web/src/composables/useFullPageCheckout.ts @@ -1,4 +1,8 @@ -import { tryOnScopeDispose, useIntervalFn } from '@vueuse/core' +import { + tryOnScopeDispose, + useEventListener, + useIntervalFn +} from '@vueuse/core' import { computed, shallowReadonly, shallowRef, watch } from 'vue' import { @@ -42,6 +46,8 @@ import { reduceCheckoutPage, settledPlanSource } from '@/checkout/checkoutPage' +import { methodKindOf } from '@/checkout/checkoutJourney' +import { endingOf } from '@/checkout/endingScreen' import { pricingTableUrl } from '@/checkout/cloudLinks' import { createOperationChannel } from '@/checkout/operationChannel' import { promoEntryLive, promoRejectionOf } from '@/checkout/promoEntry' @@ -63,6 +69,7 @@ import { useCheckoutJourney } from '@/composables/useCheckoutJourney' import { useCheckoutPromo } from '@/composables/useCheckoutPromo' import { awaitBillingWebStripeKey } from '@/config/stripeKey' import { useBillingEntry } from '@/entry/billingEntry' +import type { BillingEntryState } from '@/entry/billingEntry' import { useBillingWebSession } from '@/session/billingWebSession' import { createDeferredStripeChallengePort } from '@/session/stripeChallengePort' import { @@ -160,6 +167,13 @@ function railOf( } as const } +/** A link that names no plan has nothing to quote, so it is as unreadable as a malformed one. */ +function arrivalPage({ entry, error }: BillingEntryState): CheckoutPage { + return error.value === undefined && entry.value?.plan !== undefined + ? RESOLVING + : UNREADABLE_LINK +} + /** * The full-page checkout's effects around one `CheckoutPage` state: the * reconciliation with whatever operation the workspace is already waiting @@ -191,11 +205,8 @@ export function useFullPageCheckout() { const journey = useCheckoutJourney('full_page') journey.enter() - /** A link that names no plan has nothing to quote, so it is as unreadable as a malformed one. */ const page = shallowRef( - unreadableLink.value === undefined && entry.value?.plan !== undefined - ? RESOLVING - : UNREADABLE_LINK + arrivalPage({ entry, error: unreadableLink }) ) /** Busy from the Pay click until the attempt resolves, whatever the lifecycle's promise does. */ @@ -211,11 +222,19 @@ export function useFullPageCheckout() { * reopens only a challenge that stays on this page (below), and anything * else waits for Complete verification. */ + let handedToHostedStep = false const checkout = useCheckout({ - openUrl: (url) => window.location.assign(url), + openUrl: (url) => { + handedToHostedStep = true + window.location.assign(url) + }, navigationMode: 'redirect', challengePort, - autoContinue: () => submitting.value + autoContinue: () => submitting.value, + methodKind: () => + page.value.kind === 'capture' && page.value.attempt.kind === 'sent' + ? methodKindOf(page.value.attempt.redirectMethod) + : undefined }) const attempts = createSubscriptionCheckoutTelemetry({ ui: 'full_page' }) @@ -583,6 +602,46 @@ export function useFullPageCheckout() { const { returnLink, openedByScript, close } = useCheckoutExit(page) + watch( + () => endingOf(page.value)?.kind, + (kind) => { + if (kind === undefined) { + journey.resumed() + return + } + const current = page.value + journey.ended( + kind, + current.kind === 'terminal' ? current.attribution : undefined + ) + }, + { immediate: true } + ) + + /** + * A page handed to a method's own site by the challenge of the operation + * its Pay issued has not been abandoned. + */ + function leftForPayment() { + const current = page.value + if (current.kind !== 'capture' || current.attempt.kind !== 'sent') + return false + const { redirectMethod, operation } = current.attempt + const challenge = operation?.challenge?.status + return ( + redirectMethod !== undefined && + operation?.presentation === 'embedded' && + (challenge === 'required' || challenge === 'in_progress') + ) + } + + /** A hosted handoff covers only the page exit it caused, not one after coming Back. */ + useEventListener(window, 'pagehide', () => { + const handedOff = handedToHostedStep + handedToHostedStep = false + if (!handedOff && !leftForPayment()) journey.abandoned('page_exit') + }) + /** * The live catalog, on the Team tab when the link asked for a team plan: * one the quote named without its stop, or a link that carries a stop. @@ -797,6 +856,7 @@ export function useFullPageCheckout() { viewPlansLink, openedByScript, close, + abandon: journey.abandoned, retryLoad, onPaymentPhase, savedMethods: saved.methods, diff --git a/apps/billing-web/src/telemetry/billingWebTelemetry.test.ts b/apps/billing-web/src/telemetry/billingWebTelemetry.test.ts index a50c1e175eb..e950d76c595 100644 --- a/apps/billing-web/src/telemetry/billingWebTelemetry.test.ts +++ b/apps/billing-web/src/telemetry/billingWebTelemetry.test.ts @@ -354,6 +354,27 @@ describe('trackCheckoutJourneyEvent', () => { ) }) + it('sends an abandoned checkout to PostHog by beacon, since the page is going away', async () => { + const telemetry = createBillingWebTelemetry() + await telemetry.startPostHog({ + config: Promise.resolve(CONFIGURED), + identity: ref({ kind: 'unknown' }) + }) + + telemetry.trackCheckoutJourneyEvent({ + ...ENTERED, + phase: 'abandoned', + last_phase: 'entered', + exit: 'page_exit' + }) + + expect(posthog.capture).toHaveBeenCalledExactlyOnceWith( + 'billing.checkout.abandoned', + expect.objectContaining({ last_phase: 'entered', exit: 'page_exit' }), + { transport: 'sendBeacon' } + ) + }) + it('holds back the journey phases the backend switched off, and only those', async () => { const telemetry = createBillingWebTelemetry() await telemetry.startPostHog({ diff --git a/apps/billing-web/src/telemetry/billingWebTelemetry.ts b/apps/billing-web/src/telemetry/billingWebTelemetry.ts index c13cfb1e5d8..0efdbf5a5be 100644 --- a/apps/billing-web/src/telemetry/billingWebTelemetry.ts +++ b/apps/billing-web/src/telemetry/billingWebTelemetry.ts @@ -54,6 +54,8 @@ interface BillingEvent { | CheckoutJourneyTelemetryEventName | WebSessionTelemetryEvent['name'] readonly properties: Readonly> + /** Sent while the page goes away, after PostHog has drained its queue on `pagehide`. */ + readonly onPageExit?: true } interface IdentitySink { @@ -181,8 +183,12 @@ export function createBillingWebTelemetry() { posthog.waiting.push(event) return case 'ready': - if (!posthog.disabledEvents.has(event.name)) - posthog.client.capture(event.name, event.properties) + if (posthog.disabledEvents.has(event.name)) return + if (event.onPageExit) + posthog.client.capture(event.name, event.properties, { + transport: 'sendBeacon' + }) + else posthog.client.capture(event.name, event.properties) } } @@ -244,7 +250,8 @@ export function createBillingWebTelemetry() { properties: { ...getCheckoutJourneyTelemetryEventPayload(event), billing_surface: 'billing_web' - } + }, + ...(event.phase === 'abandoned' && { onPageExit: true }) }) ) } diff --git a/apps/billing-web/src/test/fakeBillingClient.ts b/apps/billing-web/src/test/fakeBillingClient.ts index fb932466d75..69f49336cdd 100644 --- a/apps/billing-web/src/test/fakeBillingClient.ts +++ b/apps/billing-web/src/test/fakeBillingClient.ts @@ -80,6 +80,9 @@ export interface FakeBillingClient { readonly reportChallengeStarted: Mock< BillingClient['lifecycle']['reportChallengeStarted'] > + readonly reportHostedStepOpened: Mock< + BillingClient['lifecycle']['reportHostedStepOpened'] + > readonly reportChallengeSettled: Mock< BillingClient['lifecycle']['reportChallengeSettled'] > @@ -177,6 +180,9 @@ export function createFakeBillingClient( const reportChallengeStarted: Mock< BillingClient['lifecycle']['reportChallengeStarted'] > = vi.fn() + const reportHostedStepOpened: Mock< + BillingClient['lifecycle']['reportHostedStepOpened'] + > = vi.fn() const reportChallengeSettled: Mock< BillingClient['lifecycle']['reportChallengeSettled'] > = vi.fn() @@ -261,6 +267,7 @@ export function createFakeBillingClient( switchPresentation: unusedByHostedSurfaces( 'lifecycle.switchPresentation' ), + reportHostedStepOpened, reportChallengeStarted, reportChallengeSettled, get: (id) => operations.get(id), @@ -344,6 +351,7 @@ export function createFakeBillingClient( readPlans, readPaymentMethods, invalidatePaymentMethods, + reportHostedStepOpened, reportChallengeStarted, reportChallengeSettled, previewSubscribe, diff --git a/apps/billing-web/src/views/FullPageCheckoutView.journey.test.ts b/apps/billing-web/src/views/FullPageCheckoutView.journey.test.ts index 0cb50db5db6..b494db27f79 100644 --- a/apps/billing-web/src/views/FullPageCheckoutView.journey.test.ts +++ b/apps/billing-web/src/views/FullPageCheckoutView.journey.test.ts @@ -22,6 +22,7 @@ import type { } from '@/test/fakeBillingClient' import { createFakeBillingClient, + hostedPendingOperation, pendingOperation, previewOf, succeededOperation @@ -318,8 +319,13 @@ describe('the full-page checkout journey', () => { ])('$name', async ({ options, arrange, path, last }) => { await renderCheckout(options, arrange, path) - await waitFor(() => expect(journey()).toHaveLength(2)) - expect(journeyNames()[0]).toBe('billing.checkout.entered') + await waitFor(() => + expect(journeyNames()).toEqual([ + 'billing.checkout.entered', + 'billing.checkout.preview_failed', + 'billing.checkout.ended' + ]) + ) expect(journey()[1]).toMatchObject(last) }) @@ -416,7 +422,8 @@ describe('the full-page checkout journey', () => { 'billing.checkout.payment_submit_attempted', 'billing.checkout.method_selected', 'billing.checkout.submitted', - 'billing.checkout.operation_linked' + 'billing.checkout.operation_linked', + 'billing.checkout.ended' ]) ) const [, , , , , submitted, linked] = journey() @@ -824,3 +831,182 @@ describe('the full-page operation a Pay links', () => { expect(linked()).toMatchObject([{ billing_op_id: 'op_9' }]) }) }) + +describe('the full-page checkout exits and endings', () => { + beforeEach(() => { + vi.mocked(datadogRum.getInitConfiguration).mockReturnValue({ + clientToken: 'pub', + applicationId: 'app' + }) + vi.spyOn(window.location, 'assign').mockImplementation(() => {}) + }) + + const leavePage = () => { + window.dispatchEvent(new PageTransitionEvent('pagehide')) + } + const exitsOf = () => + journey().filter(({ name }) => name === 'billing.checkout.abandoned') + + it.for<{ name: string; leave: () => Promise | void; exit: string }>([ + { name: 'the page goes away', leave: leavePage, exit: 'page_exit' }, + { + name: 'the customer goes Back', + leave: () => + userEvent.click(screen.getByRole('button', { name: 'Back' })), + exit: 'back' + } + ])( + 'reports a checkout abandoned once, at its last phase, when $name', + async ({ leave, exit }) => { + await renderCheckout() + await waitFor(() => + expect(journeyNames()).toContain('billing.checkout.preview_ready') + ) + + await leave() + leavePage() + + expect(exitsOf()).toEqual([ + expect.objectContaining({ + phase: 'abandoned', + last_phase: 'preview_ready', + exit, + billing_surface: 'billing_web' + }) + ]) + } + ) + + async function payWithAlipayHeld() { + const fake = await renderCheckout() + await screen.findByText('Subscribe to Creator Plan · Acme Team') + fake.subscribe.mockImplementation(() => new Promise(() => {})) + reportPhase({ phase: 'payment_element_ready', element: 'payment' }) + form.emit('confirm', 'ctoken_1', 'alipay') + await waitFor(() => expect(fake.subscribe).toHaveBeenCalled()) + return fake + } + + it('reports an abandon for a page that closes while its Alipay request is still pending', async () => { + await payWithAlipayHeld() + + leavePage() + + expect(exitsOf()).toEqual([ + expect.objectContaining({ last_phase: 'submitted', exit: 'page_exit' }) + ]) + }) + + it('reports no abandon for a page whose Alipay challenge took it to the provider', async () => { + const fake = await payWithAlipayHeld() + fake.publishOperation({ + ...pendingOperation('op_3ds'), + authenticationState: 'requires_action', + challenge: { clientSecret: 'cs', status: 'in_progress' } + }) + await nextTick() + + leavePage() + + expect(exitsOf()).toEqual([]) + }) + + it('reports an abandon for a page the customer came Back to from a hosted step, then closed', async () => { + const fake = await renderCheckout() + await screen.findByText('Subscribe to Creator Plan · Acme Team') + fake.subscribe.mockImplementation(() => new Promise(() => {})) + reportPhase({ phase: 'payment_element_ready', element: 'payment' }) + form.emit('confirm', 'ctoken_1', 'card') + await waitFor(() => expect(fake.subscribe).toHaveBeenCalled()) + const hosted = hostedPendingOperation('https://pay.test/3ds', 'op_hosted') + fake.publishOperation(hosted) + await waitFor(() => + expect(window.location.assign).toHaveBeenCalledWith( + 'https://pay.test/3ds' + ) + ) + leavePage() + expect(exitsOf()).toEqual([]) + + fake.recover.mockResolvedValue({ status: 'ok', value: hosted }) + const restored = new Event('pageshow') + Object.defineProperty(restored, 'persisted', { value: true }) + window.dispatchEvent(restored) + await waitFor(() => expect(fake.recover).toHaveBeenCalledTimes(2)) + leavePage() + + expect(exitsOf()).toEqual([ + expect.objectContaining({ phase: 'abandoned', exit: 'page_exit' }) + ]) + }) + + it('reports an abandon after an ending the customer retried past', async () => { + await renderCheckout({}, (fake) => + fake.readCapabilities.mockResolvedValueOnce({ + status: 'error', + code: 'REQUEST_FAILED' + }) + ) + await waitFor(() => + expect(journeyNames()).toContain('billing.checkout.ended') + ) + await userEvent.click(screen.getByRole('button', { name: 'Try again' })) + await waitFor(() => + expect(journeyNames()).toContain('billing.checkout.preview_ready') + ) + + leavePage() + + expect(exitsOf()).toEqual([ + expect.objectContaining({ + last_phase: 'preview_ready', + exit: 'page_exit' + }) + ]) + }) + + it('reports the ending its own payment reached, and no abandon after it', async () => { + const fake = await renderCheckout({ + subscribe: { + status: 'ok', + value: { phase: 'succeeded', operation: succeededOperation('op_9') } + } + }) + await screen.findByText('Subscribe to Creator Plan · Acme Team') + reportPhase({ phase: 'payment_element_ready', element: 'payment' }) + form.emit('confirm', 'ctoken_1', 'card') + await waitFor(() => expect(fake.subscribe).toHaveBeenCalled()) + await waitFor(() => + expect(journeyNames()).toContain('billing.checkout.ended') + ) + + leavePage() + + expect( + journey().filter(({ name }) => name === 'billing.checkout.ended') + ).toEqual([ + expect.objectContaining({ + phase: 'ended', + ending_kind: 'success', + attribution: 'started' + }) + ]) + expect(exitsOf()).toEqual([]) + }) + + it('reports an ending no payment reached without an attribution', async () => { + await renderCheckout({ + capabilities: {}, + denials: { can_subscribe_self_serve: 'not_workspace_owner' } + }) + + await waitFor(() => + expect(journeyNames()).toContain('billing.checkout.ended') + ) + const [ended] = journey().filter( + ({ name }) => name === 'billing.checkout.ended' + ) + expect(ended).toMatchObject({ ending_kind: 'refused' }) + expect(ended).not.toHaveProperty('attribution') + }) +}) diff --git a/apps/billing-web/src/views/FullPageCheckoutView.test.ts b/apps/billing-web/src/views/FullPageCheckoutView.test.ts index 554ee3d877c..887dfb8a700 100644 --- a/apps/billing-web/src/views/FullPageCheckoutView.test.ts +++ b/apps/billing-web/src/views/FullPageCheckoutView.test.ts @@ -2060,6 +2060,23 @@ describe('FullPageCheckoutView payment authentication', () => { nextStep.asked = 0 }) + it.for([ + { methodType: 'alipay', reported: [['op_3ds', 'redirect', 'alipay']] }, + { methodType: 'card', reported: [] } + ])( + 'reports the challenge a $methodType Pay drives as a redirect only when it finishes on another site', + async ({ methodType, reported }) => { + const fake = await payHeld(methodType) + + fake.publishOperation(challengedOperation('op_3ds', 'required')) + + await waitFor(() => + expect(fake.reportChallengeStarted).toHaveBeenCalledWith('op_3ds') + ) + expect(fake.reportHostedStepOpened.mock.calls).toEqual(reported) + } + ) + it('cancels its own challenge once however often Cancel payment is clicked, then frees the form as typed', async () => { let answer: (result: CancelOperationResult) => void = () => {} const fake = await payReady() diff --git a/apps/billing-web/src/views/FullPageCheckoutView.vue b/apps/billing-web/src/views/FullPageCheckoutView.vue index 92853a2674b..d7100ec3176 100644 --- a/apps/billing-web/src/views/FullPageCheckoutView.vue +++ b/apps/billing-web/src/views/FullPageCheckoutView.vue @@ -38,6 +38,7 @@ const { viewPlansLink, openedByScript, close, + abandon, retryLoad, onPaymentPhase, savedMethods, @@ -154,6 +155,7 @@ const endingPlan = computed(() => { function goBack() { reportReturnClicked('back') + abandon('back') window.location.assign(returnLink.value) } diff --git a/packages/account-core/src/core/billing/operationLifecycle.test.ts b/packages/account-core/src/core/billing/operationLifecycle.test.ts index 63388563a05..ed678757337 100644 --- a/packages/account-core/src/core/billing/operationLifecycle.test.ts +++ b/packages/account-core/src/core/billing/operationLifecycle.test.ts @@ -1557,11 +1557,15 @@ describe('createBillingOperationLifecycle', () => { describe('payment friction telemetry', () => { function frictionOf(telemetry: BillingOperationTelemetryEvent[]) { return telemetry - .filter((event) => event.name.startsWith('billing.checkout.')) - .map(({ name, presentation, decline_reason }) => - decline_reason === undefined - ? { name, presentation } - : { name, presentation, decline_reason } + .filter((event) => event.name.startsWith('billing.checkout.challenge')) + .map((event) => + 'decline_reason' in event && event.decline_reason !== undefined + ? { + name: event.name, + presentation: event.presentation, + decline_reason: event.decline_reason + } + : { name: event.name, presentation: event.presentation } ) } @@ -1777,3 +1781,158 @@ describe('payment friction telemetry', () => { ]) }) }) + +describe('hosted redirect telemetry', () => { + const PAYMENT_PAGE = 'https://billing.example/continue' + + function redirectsOf(telemetry: BillingOperationTelemetryEvent[]) { + return telemetry.filter( + (event) => + event.name === 'billing.checkout.redirect_started' || + event.name === 'billing.checkout.returned' + ) + } + + it('reports the hosted step the host opened, where it leads and how', async () => { + const { lifecycle, telemetry } = harness({ + destination: 'billing_web', + answers: [ + httpOk( + opStatus({ + phase: 'awaiting_payment_method', + action_url: PAYMENT_PAGE + }) + ) + ] + }) + await lifecycle.begin( + 'subscription', + issued({ operationId: 'op-1', actionUrl: PAYMENT_PAGE }) + ) + await flush() + + lifecycle.reportHostedStepOpened('op-1', 'redirect', 'alipay') + + expect(redirectsOf(telemetry)).toEqual([ + { + name: 'billing.checkout.redirect_started', + billing_op_id: 'op-1', + operation_type: 'subscription', + presentation: 'hosted', + resumed: false, + destination: 'billing_web', + step: 'payment_method', + navigation: 'redirect', + method_kind: 'alipay' + } + ]) + }) + + it.for([ + { + server: { authentication_state: 'requires_action' }, + step: 'authentication' + }, + { server: { phase: 'awaiting_invoice_payment' }, step: 'invoice_payment' }, + { server: { phase: 'in_progress' }, step: 'checkout' } + ] as const)( + 'names the hosted step $step from what the server waits on', + async ({ server, step }) => { + const { lifecycle, telemetry } = harness({ + answers: [httpOk(opStatus({ ...server, action_url: PAYMENT_PAGE }))] + }) + await lifecycle.begin('topup', issued()) + await flush() + + lifecycle.reportHostedStepOpened('op-1', 'new_tab') + + expect(redirectsOf(telemetry)).toEqual([ + expect.objectContaining({ step, destination: 'stripe' }) + ]) + } + ) + + it('reports the return once when the page the redirect left recovers the operation', async () => { + const storage = memoryStorage() + const left = harness({ + storage, + answers: [ + httpOk( + opStatus({ + phase: 'awaiting_payment_method', + action_url: PAYMENT_PAGE + }) + ) + ] + }) + await left.lifecycle.begin( + 'subscription', + issued({ operationId: 'op-1', actionUrl: PAYMENT_PAGE }) + ) + await flush() + left.lifecycle.reportHostedStepOpened('op-1', 'redirect', 'alipay') + left.lifecycle.dispose() + + const pending = statusSnapshot({ + pending_billing_op_id: 'op-1', + pending_billing_op_type: 'subscription' + }) + const back = harness({ storage, status: pending }) + await back.lifecycle.recover() + const reloaded = harness({ storage, status: pending }) + await reloaded.lifecycle.recover() + + expect(redirectsOf(back.telemetry)).toEqual([ + { + name: 'billing.checkout.returned', + billing_op_id: 'op-1', + operation_type: 'subscription', + presentation: 'hosted', + resumed: true, + destination: 'stripe', + step: 'payment_method', + navigation: 'redirect', + method_kind: 'alipay' + } + ]) + expect(redirectsOf(reloaded.telemetry)).toEqual([]) + }) + + it('reports the return once when the customer comes back to this tab from a new one', async () => { + const { lifecycle, telemetry } = harness({ + answers: [httpOk(opStatus({ action_url: PAYMENT_PAGE }))] + }) + await lifecycle.begin('topup', issued()) + await flush() + lifecycle.reportHostedStepOpened('op-1', 'new_tab') + + lifecycle.wake() + lifecycle.wake() + + expect(redirectsOf(telemetry)).toEqual([ + expect.objectContaining({ + name: 'billing.checkout.redirect_started', + navigation: 'new_tab' + }), + expect.objectContaining({ + name: 'billing.checkout.returned', + navigation: 'new_tab' + }) + ]) + }) + + it('reports no return for a page that redirected away and was never reloaded', async () => { + const { lifecycle, telemetry } = harness({ + answers: [httpOk(opStatus({ action_url: PAYMENT_PAGE }))] + }) + await lifecycle.begin('topup', issued()) + await flush() + lifecycle.reportHostedStepOpened('op-1', 'redirect') + + lifecycle.wake() + + expect(redirectsOf(telemetry).map((event) => event.name)).toEqual([ + 'billing.checkout.redirect_started' + ]) + }) +}) diff --git a/packages/account-core/src/core/billing/operationLifecycle.ts b/packages/account-core/src/core/billing/operationLifecycle.ts index fe1503427f7..6ee159394dc 100644 --- a/packages/account-core/src/core/billing/operationLifecycle.ts +++ b/packages/account-core/src/core/billing/operationLifecycle.ts @@ -65,6 +65,11 @@ import { validateActionUrl } from './operationState.js' import type { PaymentFrictionSignal } from './paymentFriction.js' +import type { + CheckoutHostedStep, + CheckoutRedirectNavigation +} from './telemetry/checkoutRedirectEvent.js' +import type { CheckoutMethodKind } from './telemetry/checkoutJourney.js' import { paymentFrictionBetween } from './paymentFriction.js' import { selectBillingPresentation } from './presentation.js' import { readValidatedBillingResponse } from './sharedRead.js' @@ -95,23 +100,44 @@ export type BillingOperationFailureCategory = | 'reconciliation_needed' | 'stale_operation' -type BillingOperationTelemetryEventName = +type HostedStepEventName = + | typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.redirectStarted + | typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned + +type BillingOperationTelemetryEventName = Exclude< | (typeof BILLING_OPERATION_TELEMETRY_EVENT)[keyof typeof BILLING_OPERATION_TELEMETRY_EVENT] - | (typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT)[keyof typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT] + | (typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT)[keyof typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT], + HostedStepEventName +> + +/** A hosted step this tab handed the customer to. */ +interface HostedStepVisit { + readonly destination: HostedBillingDestination + readonly step: CheckoutHostedStep + readonly navigation: CheckoutRedirectNavigation + readonly method_kind?: CheckoutMethodKind +} -export interface BillingOperationTelemetryEvent { - readonly name: BillingOperationTelemetryEventName +interface BillingOperationTelemetryBase { readonly billing_op_id: string readonly operation_type: BillingOperationKind readonly presentation: BillingPresentation /** True when this tab reattached to an operation it did not issue. */ readonly resumed: boolean - readonly failure_category?: BillingOperationFailureCategory - readonly decline_reason?: BillingDeclineReason - /** From the attempt's start, so a resumed operation reports its whole life. */ - readonly duration_ms?: number } +export type BillingOperationTelemetryEvent = BillingOperationTelemetryBase & + ( + | { + readonly name: BillingOperationTelemetryEventName + readonly failure_category?: BillingOperationFailureCategory + readonly decline_reason?: BillingDeclineReason + /** From the attempt's start, so a resumed operation reports its whole life. */ + readonly duration_ms?: number + } + | (HostedStepVisit & { readonly name: HostedStepEventName }) + ) + export type PresentationSwitchOutcome = | 'switched' | 'unchanged' @@ -182,6 +208,16 @@ export interface BillingOperationLifecycle { operationId: string, presentation: BillingPresentation ) => PresentationSwitchOutcome + /** + * The host opened the operation's hosted step. A redirect is remembered in + * the pointer, so the page it returns to reports the return; a new tab + * reports it on the next wake. + */ + reportHostedStepOpened: ( + operationId: string, + navigation: CheckoutRedirectNavigation, + methodKind?: CheckoutMethodKind + ) => void /** The host began driving the operation's challenge; polling pauses until it settles. */ reportChallengeStarted: (operationId: string) => void reportChallengeSettled: ( @@ -226,6 +262,8 @@ interface OperationRecord { waitingWithoutActionSince: number | undefined timer: ReturnType | undefined inFlightPoll: Promise | undefined + /** A hosted step this tab opened in a new tab; the next wake is the customer back. */ + awaitingReturn: HostedStepVisit | undefined readonly settled: Promise resolveSettled: (state: BillingOperationState) => void } @@ -242,6 +280,30 @@ interface AdoptInput { readonly awaitedHere: boolean /** A status already read for this operation; observed from it instead of polled again. */ readonly initialStatus?: BillingOpStatus + /** The hosted step a redirect left this page for; adopting it is the return. */ + readonly returnedFrom?: BillingOperationPointer['redirect'] +} + +type ResumedAttempt = Pick< + AdoptInput, + | 'presentation' + | 'attemptStartedAt' + | 'resumed' + | 'awaitedHere' + | 'returnedFrom' +> + +/** The attempt a pointer remembers, picked up again by this tab. */ +function resumedFrom(pointer: BillingOperationPointer): ResumedAttempt { + return { + presentation: pointer.presentation, + attemptStartedAt: pointer.attemptStartedAt, + resumed: true, + awaitedHere: pointer.awaited === true, + ...(pointer.redirect === undefined + ? {} + : { returnedFrom: pointer.redirect }) + } } interface ServerPendingOperation { @@ -328,6 +390,19 @@ const FRICTION_EVENT_NAME = { challenge_failed: BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeFailed } as const satisfies Record +/** What the hosted page asks of the customer, from what the server waits on. */ +function hostedStepOf(state: PendingBillingOperation): CheckoutHostedStep { + if ( + state.authenticationState === 'requires_action' || + (state.presentation === 'embedded' && state.challenge !== undefined) + ) { + return 'authentication' + } + if (state.serverPhase === 'awaiting_payment_method') return 'payment_method' + if (state.serverPhase === 'awaiting_invoice_payment') return 'invoice_payment' + return 'checkout' +} + /** The pause is this tab's own challenge on screen; a hosted page never pauses. */ function isDrivingChallenge(state: PendingBillingOperation): boolean { return ( @@ -474,13 +549,33 @@ export function createBillingOperationLifecycle( return request } - function writePointer(scope: BillingScope, state: BillingOperationState) { + function writePointer( + scope: BillingScope, + state: BillingOperationState, + redirect?: BillingOperationPointer['redirect'] + ) { pointers.write(scope, { operationId: state.id, kind: state.kind, presentation: state.presentation, attemptStartedAt: state.attemptStartedAt, - ...(state.awaitedHere ? { awaited: true } : {}) + ...(state.awaitedHere ? { awaited: true } : {}), + ...(redirect === undefined ? {} : { redirect }) + }) + } + + function emitHostedStepTelemetry( + record: OperationRecord, + name: HostedStepEventName, + visit: HostedStepVisit + ) { + onTelemetry?.({ + name, + billing_op_id: record.state.id, + operation_type: record.state.kind, + presentation: record.state.presentation, + resumed: record.resumed, + ...visit }) } @@ -592,6 +687,7 @@ export function createBillingOperationLifecycle( waitingWithoutActionSince: undefined, timer: undefined, inFlightPoll: undefined, + awaitingReturn: undefined, settled, resolveSettled } @@ -605,6 +701,16 @@ export function createBillingOperationLifecycle( resumed: input.resumed }) emitFrictionTelemetry(record, undefined) + if (input.returnedFrom !== undefined) { + emitHostedStepTelemetry( + record, + BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned, + { + ...input.returnedFrom, + navigation: 'redirect' + } + ) + } startObserving(record, input, state) return record } @@ -793,10 +899,7 @@ export function createBillingOperationLifecycle( id: pointer.operationId, kind: pointer.kind, context, - presentation: pointer.presentation, - attemptStartedAt: pointer.attemptStartedAt, - resumed: true, - awaitedHere: pointer.awaited === true + ...resumedFrom(pointer) } } @@ -827,10 +930,14 @@ export function createBillingOperationLifecycle( { ...pending, context, - presentation: known?.presentation ?? routeFor(rail, pending), - attemptStartedAt: known?.attemptStartedAt ?? now(), - resumed: true, - awaitedHere: known?.awaited === true + ...(known === undefined + ? { + presentation: routeFor(rail, pending), + attemptStartedAt: now(), + resumed: true, + awaitedHere: false + } + : resumedFrom(known)) }, includeSettled ) @@ -903,6 +1010,7 @@ export function createBillingOperationLifecycle( function wake() { for (const record of operations.values()) { + reportReturnFromNewTab(record) if (record.state.phase !== 'pending') continue if (isDrivingChallenge(record.state)) continue void poll(record) @@ -951,6 +1059,44 @@ export function createBillingOperationLifecycle( return 'switched' } + function reportReturnFromNewTab(record: OperationRecord) { + const visit = record.awaitingReturn + if (visit === undefined) return + record.awaitingReturn = undefined + emitHostedStepTelemetry( + record, + BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned, + visit + ) + } + + function reportHostedStepOpened( + operationId: string, + navigation: CheckoutRedirectNavigation, + methodKind?: CheckoutMethodKind + ) { + const record = operations.get(operationId) + if (record === undefined || record.state.phase !== 'pending') return + const state = record.state + const redirect = { + destination: + state.presentation === 'hosted' ? state.hostedDestination : 'stripe', + step: hostedStepOf(state), + ...(methodKind === undefined ? {} : { method_kind: methodKind }) + } as const + const visit = { ...redirect, navigation } + if (navigation === 'redirect') { + writePointer(record.context.scope, state, redirect) + } else { + record.awaitingReturn = visit + } + emitHostedStepTelemetry( + record, + BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.redirectStarted, + visit + ) + } + function reportChallengeStarted(operationId: string) { const record = operations.get(operationId) if (record === undefined) return @@ -980,6 +1126,7 @@ export function createBillingOperationLifecycle( recover, wake, switchPresentation, + reportHostedStepOpened, reportChallengeStarted, reportChallengeSettled, get: (operationId) => operations.get(operationId)?.state, diff --git a/packages/account-core/src/core/billing/operationPointer.ts b/packages/account-core/src/core/billing/operationPointer.ts index 368e26014f3..f872c416b6c 100644 --- a/packages/account-core/src/core/billing/operationPointer.ts +++ b/packages/account-core/src/core/billing/operationPointer.ts @@ -31,7 +31,20 @@ const PointerSchema = z.object({ /** This tab issued the operation and has not yet seen it succeed. */ awaited: z.literal(true).optional(), /** The end this tab saw it reach, kept only by a store that retains settled pointers. */ - settled: z.enum(['succeeded', 'reconciliation_needed']).optional() + settled: z.enum(['succeeded', 'reconciliation_needed']).optional(), + /** The hosted step this page redirected to; the page it returns to reports the return. */ + redirect: z + .object({ + destination: z.enum(['stripe', 'billing_web']), + step: z.enum([ + 'authentication', + 'payment_method', + 'invoice_payment', + 'checkout' + ]), + method_kind: z.enum(['card', 'alipay', 'other']).optional() + }) + .optional() }) export type BillingOperationPointer = z.infer diff --git a/packages/account-core/src/core/billing/telemetry/billingTelemetryEvent.ts b/packages/account-core/src/core/billing/telemetry/billingTelemetryEvent.ts index 01578da10b9..0100e4592c7 100644 --- a/packages/account-core/src/core/billing/telemetry/billingTelemetryEvent.ts +++ b/packages/account-core/src/core/billing/telemetry/billingTelemetryEvent.ts @@ -1,6 +1,7 @@ import type { CancelBillingEvent } from './cancelEvent.js' import type { CapabilityReadBillingEvent } from './capabilityReadEvent.js' import type { CheckoutChallengeBillingEvent } from './checkoutChallengeEvent.js' +import type { CheckoutRedirectBillingEvent } from './checkoutRedirectEvent.js' import type { DowngradeToPersonalBillingEvent } from './downgradeToPersonalEvent.js' import type { EntryBillingEvent } from './entryEvent.js' import type { BillingOperationBillingEvent } from './operationEvent.js' @@ -35,6 +36,7 @@ export type BillingTelemetryEvent = { | CancelBillingEvent | PortalBillingEvent | CheckoutChallengeBillingEvent + | CheckoutRedirectBillingEvent ) type BillingTelemetryEventNameFor = diff --git a/packages/account-core/src/core/billing/telemetry/checkoutJourney.test.ts b/packages/account-core/src/core/billing/telemetry/checkoutJourney.test.ts index 2da00fd277c..241d1927e5b 100644 --- a/packages/account-core/src/core/billing/telemetry/checkoutJourney.test.ts +++ b/packages/account-core/src/core/billing/telemetry/checkoutJourney.test.ts @@ -147,6 +147,43 @@ const CASES: readonly PayloadCase[] = [ phase: 'preview_failed', failure_category: 'network' } + }, + { + name: 'an abandoned checkout names the last phase it reached and how the customer left', + event: { + ...CONTEXT, + billing_op_id: 'op-1', + phase: 'abandoned', + last_phase: 'operation_linked', + exit: 'page_exit' + }, + payload: { + ...PAYLOAD_OF_CONTEXT, + billing_op_id: 'op-1', + phase: 'abandoned', + last_phase: 'operation_linked', + exit: 'page_exit' + } + }, + { + name: 'an ending names its screen and whose payment it was', + event: { + ...CONTEXT, + phase: 'ended', + ending_kind: 'success', + attribution: 'started' + }, + payload: { + ...PAYLOAD_OF_CONTEXT, + phase: 'ended', + ending_kind: 'success', + attribution: 'started' + } + }, + { + name: 'an ending no payment reached carries no attribution', + event: { ...CONTEXT, phase: 'ended', ending_kind: 'refused' }, + payload: { ...PAYLOAD_OF_CONTEXT, phase: 'ended', ending_kind: 'refused' } } ] diff --git a/packages/account-core/src/core/billing/telemetry/checkoutJourney.ts b/packages/account-core/src/core/billing/telemetry/checkoutJourney.ts index 2e4118d1feb..01158c76a84 100644 --- a/packages/account-core/src/core/billing/telemetry/checkoutJourney.ts +++ b/packages/account-core/src/core/billing/telemetry/checkoutJourney.ts @@ -101,7 +101,7 @@ type CheckoutJourneyPaymentSubmitFailed = { error_code?: string } type CheckoutPaymentRail = 'saved' | 'new' | 'on_file' -type CheckoutMethodKind = 'card' | 'alipay' | 'other' +export type CheckoutMethodKind = 'card' | 'alipay' | 'other' type CheckoutPromoResult = 'applied' | 'rejected' | 'removed' | 'expired' type CheckoutPayBlockedReason = 'reactivation_unconfirmed' | 'promo_unapplied' @@ -126,7 +126,7 @@ type CheckoutJourneyOperationLinked = { billing_op_id: string } -export type CheckoutJourneyPhaseEvent = +type CheckoutJourneyProgressEvent = | CheckoutJourneyEntered | CheckoutJourneyPreviewReady | CheckoutJourneyPreviewFailed @@ -140,7 +140,45 @@ export type CheckoutJourneyPhaseEvent = | CheckoutJourneySubmitted | CheckoutJourneyOperationLinked -type CheckoutJourneyPhase = CheckoutJourneyPhaseEvent['phase'] +/** How the customer left: the page went away, or a control of this page led out. */ +export type CheckoutExit = 'page_exit' | 'back' | 'close' | 'host_link' +/** The ending screens of the full-page checkout. */ +export type CheckoutEndingKind = + | 'success' + | 'completed' + | 'already_completed' + | 'in_progress' + | 'received' + | 'unconfirmed' + | 'refused' + | 'plan_unavailable' + | 'link_invalid' + | 'load_failed' +/** Whose payment an ending shows: this page's Pay, a return, one it followed, or one already settled. */ +export type CheckoutEndingAttribution = + | 'started' + | 'returned' + | 'followed' + | 'settled' + +/** The customer left before the checkout reached an ending. */ +type CheckoutJourneyAbandoned = { + phase: 'abandoned' + last_phase: CheckoutJourneyProgressEvent['phase'] + exit: CheckoutExit +} +type CheckoutJourneyEnded = { + phase: 'ended' + ending_kind: CheckoutEndingKind + attribution?: CheckoutEndingAttribution +} + +export type CheckoutJourneyPhaseEvent = + | CheckoutJourneyProgressEvent + | CheckoutJourneyAbandoned + | CheckoutJourneyEnded + +export type CheckoutJourneyPhase = CheckoutJourneyPhaseEvent['phase'] export type CheckoutJourneyTelemetryEvent = CheckoutJourneyContext & CheckoutJourneyPhaseEvent @@ -168,7 +206,9 @@ export const CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE: Record< promo: 'billing.checkout.promo', pay_blocked: 'billing.checkout.pay_blocked', submitted: 'billing.checkout.submitted', - operation_linked: 'billing.checkout.operation_linked' + operation_linked: 'billing.checkout.operation_linked', + abandoned: 'billing.checkout.abandoned', + ended: 'billing.checkout.ended' } export function getCheckoutJourneyTelemetryEventName( @@ -237,6 +277,16 @@ function getChoicePayload(event: CheckoutJourneyPhaseEvent) { } } +function getExitPayload(event: CheckoutJourneyPhaseEvent) { + return { + ...('last_phase' in event && { last_phase: event.last_phase }), + ...('exit' in event && { exit: event.exit }), + ...('ending_kind' in event && { ending_kind: event.ending_kind }), + ...('attribution' in event && + event.attribution !== undefined && { attribution: event.attribution }) + } +} + export function getCheckoutJourneyTelemetryEventPayload( event: CheckoutJourneyTelemetryEvent ) { @@ -244,7 +294,8 @@ export function getCheckoutJourneyTelemetryEventPayload( ...getContextPayload(event), ...getPreviewPayload(event), ...getPaymentFormPayload(event), - ...getChoicePayload(event) + ...getChoicePayload(event), + ...getExitPayload(event) } } diff --git a/packages/account-core/src/core/billing/telemetry/checkoutRedirectEvent.ts b/packages/account-core/src/core/billing/telemetry/checkoutRedirectEvent.ts new file mode 100644 index 00000000000..226183b6644 --- /dev/null +++ b/packages/account-core/src/core/billing/telemetry/checkoutRedirectEvent.ts @@ -0,0 +1,37 @@ +import type { + BillingOperationKind, + BillingPresentation, + HostedBillingDestination +} from '../operationState.js' +import type { CheckoutMethodKind } from './checkoutJourney.js' + +/** What the hosted page asks of the customer, from what the server waits on. */ +export type CheckoutHostedStep = + | 'authentication' + | 'payment_method' + | 'invoice_payment' + | 'checkout' + +/** The hosted page replaced this page, or opened beside it. */ +export type CheckoutRedirectNavigation = 'redirect' | 'new_tab' + +/** + * A hosted step this tab handed the customer to, and the customer back on the + * tab that handed it. Neither settles the operation; the pair joins on + * `billing_op_id`, and a start with no return is a customer who did not come + * back. + */ +export type CheckoutRedirectBillingEvent = { + operation: 'checkout' + outcome: 'pending' + billing_op_id: string + operation_type: BillingOperationKind + presentation: BillingPresentation + /** True when this tab reattached to an operation it did not issue. */ + resumed?: boolean + destination: HostedBillingDestination + step: CheckoutHostedStep + navigation: CheckoutRedirectNavigation + /** The method the customer chose, when the host knows it. */ + method_kind?: CheckoutMethodKind +} & ({ stage: 'redirect_started' } | { stage: 'returned' }) diff --git a/packages/account-core/src/core/billing/telemetry/index.ts b/packages/account-core/src/core/billing/telemetry/index.ts index cc2d73df4b6..428fa7b0f9e 100644 --- a/packages/account-core/src/core/billing/telemetry/index.ts +++ b/packages/account-core/src/core/billing/telemetry/index.ts @@ -18,6 +18,10 @@ export { } from './payload.js' export { BILLING_TELEMETRY_EVENTS } from './eventNames.js' export { toBillingTelemetryEvent } from './operationLifecycleEvent.js' +export type { + CheckoutHostedStep, + CheckoutRedirectNavigation +} from './checkoutRedirectEvent.js' export type { BillingPortalTarget } from './portalEvent.js' export type { SubscriptionCheckoutUi } from './subscriptionCheckoutEvent.js' export type { @@ -37,14 +41,19 @@ export type { } from './webSessionEvent.js' export type { CheckoutAssignmentStatus, + CheckoutEndingAttribution, + CheckoutEndingKind, CheckoutEntryFlow, + CheckoutExit, CheckoutEntrySource, CheckoutJourneyArm, CheckoutJourneyContext, + CheckoutJourneyPhase, CheckoutJourneyPhaseEvent, CheckoutJourneyTelemetryEvent, CheckoutJourneyTelemetryEventName, CheckoutJourneyTelemetryEventPayload, + CheckoutMethodKind, CheckoutUiMode } from './checkoutJourney.js' export { diff --git a/packages/account-core/src/core/billing/telemetry/operationLifecycleEvent.test.ts b/packages/account-core/src/core/billing/telemetry/operationLifecycleEvent.test.ts index c3eefe5100f..572675fabd3 100644 --- a/packages/account-core/src/core/billing/telemetry/operationLifecycleEvent.test.ts +++ b/packages/account-core/src/core/billing/telemetry/operationLifecycleEvent.test.ts @@ -186,6 +186,60 @@ describe('toBillingTelemetryEvent', () => { resumed: false, decline_reason: 'card_declined' } + }, + { + name: 'a hosted step opened, with where it leads and the method', + event: { + name: 'billing.checkout.redirect_started', + billing_op_id: 'op-redirect', + operation_type: 'subscription', + presentation: 'hosted', + resumed: false, + destination: 'stripe', + step: 'payment_method', + navigation: 'redirect', + method_kind: 'alipay' + }, + expected: { + operation: 'checkout', + billing_client: 'sdk', + stage: 'redirect_started', + outcome: 'pending', + operation_type: 'subscription', + billing_op_id: 'op-redirect', + presentation: 'hosted', + resumed: false, + destination: 'stripe', + step: 'payment_method', + navigation: 'redirect', + method_kind: 'alipay' + } + }, + { + name: 'a return from a hosted step, without a method the host never knew', + event: { + name: 'billing.checkout.returned', + billing_op_id: 'op-redirect', + operation_type: 'topup', + presentation: 'hosted', + resumed: true, + destination: 'billing_web', + step: 'authentication', + navigation: 'new_tab' + }, + expected: { + operation: 'checkout', + billing_client: 'sdk', + stage: 'returned', + outcome: 'pending', + operation_type: 'topup', + billing_op_id: 'op-redirect', + presentation: 'hosted', + resumed: true, + destination: 'billing_web', + step: 'authentication', + navigation: 'new_tab' + } } ])('maps $name', ({ event, expected }) => { expect(toBillingTelemetryEvent(event)).toEqual(expected) diff --git a/packages/account-core/src/core/billing/telemetry/operationLifecycleEvent.ts b/packages/account-core/src/core/billing/telemetry/operationLifecycleEvent.ts index 4383c3602a9..8841c01125e 100644 --- a/packages/account-core/src/core/billing/telemetry/operationLifecycleEvent.ts +++ b/packages/account-core/src/core/billing/telemetry/operationLifecycleEvent.ts @@ -24,6 +24,24 @@ export function toBillingTelemetryEvent( presentation: event.presentation, resumed: event.resumed } as const + if ( + event.name === BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.redirectStarted || + event.name === BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned + ) { + return { + ...friction, + stage: + event.name === BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.returned + ? 'returned' + : 'redirect_started', + destination: event.destination, + step: event.step, + navigation: event.navigation, + ...(event.method_kind === undefined + ? {} + : { method_kind: event.method_kind }) + } + } const shared = { operation: 'operation', billing_client: 'sdk', @@ -34,9 +52,9 @@ export function toBillingTelemetryEvent( ...(paymentIntentSource === undefined ? {} : { payment_intent_source: paymentIntentSource }), - ...(event.duration_ms === undefined - ? {} - : { duration_ms: event.duration_ms }) + ...('duration_ms' in event && event.duration_ms !== undefined + ? { duration_ms: event.duration_ms } + : {}) } as const switch (event.name) { diff --git a/packages/account-core/src/core/billing/telemetry/payload.ts b/packages/account-core/src/core/billing/telemetry/payload.ts index f17c3b00eb0..816dedd8914 100644 --- a/packages/account-core/src/core/billing/telemetry/payload.ts +++ b/packages/account-core/src/core/billing/telemetry/payload.ts @@ -16,18 +16,21 @@ export const BILLING_PAYLOAD_FIELD_HANDLING = { checkout_status: 'required', control: 'required', correlation_id: 'required', + destination: 'required', failure_category: 'required', has_plan: 'required', intent: 'required', member_removal_count: 'required', member_removal_failures: 'required', mode: 'required', + navigation: 'required', operation_type: 'required', origin: 'required', product: 'required', reason: 'required', result: 'required', source: 'required', + step: 'required', target: 'required', to: 'required', amount_cents: 'optional', @@ -42,6 +45,7 @@ export const BILLING_PAYLOAD_FIELD_HANDLING = { decline_reason: 'optional', duration_ms: 'optional', error_code: 'optional', + method_kind: 'optional', payment_intent_source: 'optional', presentation: 'optional', recovery_outcome: 'optional', diff --git a/packages/account-core/src/telemetry.ts b/packages/account-core/src/telemetry.ts index a56536692e3..71d4e934dd8 100644 --- a/packages/account-core/src/telemetry.ts +++ b/packages/account-core/src/telemetry.ts @@ -58,12 +58,15 @@ export const BILLING_OPERATION_TELEMETRY_EVENT = { /** * Payment friction the lifecycle observes inside one operation: a bank - * challenge and its verdict, and each retryable decline. + * challenge and its verdict, each retryable decline, and a hosted step the + * customer was sent to and came back from. */ export const BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT = { challengeRequired: 'billing.checkout.challenge_required', challengeCompleted: 'billing.checkout.challenge_completed', - challengeFailed: 'billing.checkout.challenge_failed' + challengeFailed: 'billing.checkout.challenge_failed', + redirectStarted: 'billing.checkout.redirect_started', + returned: 'billing.checkout.returned' } as const export const AUTH_TELEMETRY_EVENT = { diff --git a/packages/account-ui/src/billing/__fixtures__/billingHarness.ts b/packages/account-ui/src/billing/__fixtures__/billingHarness.ts index 6a5a381fa0a..de79d444e5d 100644 --- a/packages/account-ui/src/billing/__fixtures__/billingHarness.ts +++ b/packages/account-ui/src/billing/__fixtures__/billingHarness.ts @@ -7,6 +7,7 @@ import { vi } from 'vitest' import type { BillingHttpResponse, + BillingOperationTelemetryEvent, BillingOpStatus, BillingRequest, BillingResult, @@ -239,11 +240,13 @@ export function createBillingHarness(options: HarnessOptions = {}) { const plans = createPlansReader(readerOptions) const paymentMethods = createPaymentMethodsReader(readerOptions) const events = createBillingEventsReader(readerOptions) + const telemetry: BillingOperationTelemetryEvent[] = [] const lifecycle = createBillingOperationLifecycle({ transport, scopeSource, statusReader, - embeddedCheckoutAvailable: () => options.embedded === true + embeddedCheckoutAvailable: () => options.embedded === true, + onTelemetry: (event) => telemetry.push(event) }) let attempts = 0 const idempotencyKey = () => `key-${++attempts}` @@ -308,6 +311,7 @@ export function createBillingHarness(options: HarnessOptions = {}) { calls, answer, routes, + telemetry, /** Moves the host to another workspace, as the switcher does. */ moveToWorkspace: (id: string) => host.moveTo({ id, name: 'Team', type: 'team' }) diff --git a/packages/account-ui/src/billing/useCheckout.test.ts b/packages/account-ui/src/billing/useCheckout.test.ts index fdadc0bea85..6ca2dcf81f8 100644 --- a/packages/account-ui/src/billing/useCheckout.test.ts +++ b/packages/account-ui/src/billing/useCheckout.test.ts @@ -59,6 +59,61 @@ describe('useCheckout', () => { expect(openUrl).toHaveBeenCalledExactlyOnceWith(PAYMENT_PAGE, 'new_tab') }) + it.for([ + { navigationMode: 'redirect', navigation: 'redirect' }, + { navigationMode: 'new_tab', navigation: 'new_tab' }, + { navigationMode: 'preopened', navigation: 'new_tab' } + ] as const)( + 'reports the hosted step as a $navigation, with the host method, before the host leaves for it ($navigationMode)', + async ({ navigationMode, navigation }) => { + const { client, answer, telemetry } = createBillingHarness() + answer( + 'POST', + SUBSCRIBE_ROUTE, + httpOk({ + billing_op_id: 'op-1', + status: 'needs_payment_method', + payment_method_url: PAYMENT_PAGE + }) + ) + answer( + 'GET', + operationRoute('op-1'), + httpOk( + opStatus({ + phase: 'awaiting_payment_method', + action_url: PAYMENT_PAGE + }) + ) + ) + const reportedWhenOpened: string[][] = [] + const openUrl = vi.fn(() => { + reportedWhenOpened.push(telemetry.map((event) => event.name)) + }) + + const checkout = useCheckout({ + client, + openUrl, + navigationMode, + autoContinue: () => false, + methodKind: () => 'alipay' + }) + void checkout.subscribe(PLAN) + await vi.advanceTimersByTimeAsync(0) + checkout.continueVerification() + + expect(reportedWhenOpened).toEqual([ + ['billing.operation.started', 'billing.checkout.redirect_started'] + ]) + expect(telemetry[1]).toMatchObject({ + destination: 'stripe', + step: 'payment_method', + navigation, + method_kind: 'alipay' + }) + } + ) + it('hands the hosted payment page the server offered to the host and settles the subscription', async () => { const { client, answer, calls } = createBillingHarness() answer( diff --git a/packages/account-ui/src/billing/usePaymentAttempt.ts b/packages/account-ui/src/billing/usePaymentAttempt.ts index ac944bc8d46..9bc290cd8c6 100644 --- a/packages/account-ui/src/billing/usePaymentAttempt.ts +++ b/packages/account-ui/src/billing/usePaymentAttempt.ts @@ -12,6 +12,7 @@ import type { Ref } from 'vue' import type { BillingOperationKind, BillingOperationState, + CheckoutMethodKind, EmbeddedChallengePort, HostPaymentStep, PaymentProjection, @@ -43,6 +44,8 @@ export interface PaymentNavigation { * that declines one runs it later through `continueVerification`. */ readonly autoContinue?: (state: PendingBillingOperation) => boolean + /** The method the customer chose, reported with the hosted step it leads to. */ + readonly methodKind?: () => CheckoutMethodKind | undefined } export interface PaymentAttempt { @@ -71,6 +74,18 @@ function continuationKey( : undefined } +/** A non-card method finishes its challenge on the provider's site. */ +function leavesForProvider( + state: PendingBillingOperation, + method: CheckoutMethodKind | undefined +): boolean { + return ( + state.challenge?.status === 'required' && + method !== undefined && + method !== 'card' + ) +} + export function usePaymentAttempt( kind: BillingOperationKind, client: Pick, @@ -80,7 +95,8 @@ export function usePaymentAttempt( openUrl, navigationMode = 'new_tab', challengePort, - autoContinue = () => true + autoContinue = () => true, + methodKind = () => undefined } = navigation const tracked = useBillingOperation({ kind }, client) const dismissedId = ref() @@ -97,17 +113,36 @@ export function usePaymentAttempt( projectPaymentStep(operation.value, hostStep.value) ) + function openHostedStep( + state: PendingBillingOperation, + method: CheckoutMethodKind | undefined + ) { + if (state.actionUrl === undefined) return + client.lifecycle.reportHostedStepOpened( + state.id, + navigationMode === 'redirect' ? 'redirect' : 'new_tab', + method + ) + openUrl(state.actionUrl, navigationMode) + } + + function driveChallenge( + state: PendingBillingOperation, + method: CheckoutMethodKind | undefined + ) { + if (challengePort === undefined) return + if (leavesForProvider(state, method)) { + client.lifecycle.reportHostedStepOpened(state.id, 'redirect', method) + } + void driveEmbeddedChallenge(client.lifecycle, state.id, challengePort) + } + function continueVerification() { const state = operation.value if (state?.phase !== 'pending') return - if (state.presentation === 'hosted') { - if (state.actionUrl !== undefined) { - openUrl(state.actionUrl, navigationMode) - } - return - } - if (challengePort === undefined) return - void driveEmbeddedChallenge(client.lifecycle, state.id, challengePort) + const method = methodKind() + if (state.presentation === 'hosted') openHostedStep(state, method) + else driveChallenge(state, method) } // Once per continuation the server offers; a resumed operation is not diff --git a/src/platform/workspace/billing/sdk/billingSdkStore.test.ts b/src/platform/workspace/billing/sdk/billingSdkStore.test.ts index 4c9bfe33dcd..92eb37fe8fe 100644 --- a/src/platform/workspace/billing/sdk/billingSdkStore.test.ts +++ b/src/platform/workspace/billing/sdk/billingSdkStore.test.ts @@ -857,6 +857,25 @@ describe('useBillingSdkStore subscription commands', () => { ) }) + it.for([ + { page: 'opened', opened: window, reported: [['op-1', 'new_tab']] }, + { page: 'had blocked', opened: null, reported: [] } + ])( + 'reports to the lifecycle a hosted page it $page in a new tab', + ({ opened, reported }) => { + vi.spyOn(window, 'open').mockReturnValue(opened) + useBillingSdkStore() + + harness.publish( + pendingSubscription({ actionUrl: 'https://pay.example/first' }) + ) + + expect( + vi.mocked(harness.sdk.lifecycle.reportHostedStepOpened).mock.calls + ).toEqual(reported) + } + ) + it('offers the next hosted page the same subscribe moves to', () => { const openPage = vi.spyOn(window, 'open').mockReturnValue(null) const store = useBillingSdkStore() diff --git a/src/platform/workspace/billing/sdk/billingSdkStore.ts b/src/platform/workspace/billing/sdk/billingSdkStore.ts index 15b85ba1c2f..9b1a44f9a7b 100644 --- a/src/platform/workspace/billing/sdk/billingSdkStore.ts +++ b/src/platform/workspace/billing/sdk/billingSdkStore.ts @@ -373,7 +373,10 @@ export const useBillingSdkStore = defineStore('billingSdk', () => { const offered = offeredActions.get(state.id) ?? new Set() if (offered.has(actionUrl)) return offeredActions.set(state.id, offered.add(actionUrl)) - if (window.open(actionUrl, '_blank')) return + if (window.open(actionUrl, '_blank')) { + sdk.lifecycle.reportHostedStepOpened(state.id, 'new_tab') + return + } toastStore.add({ severity: 'warn', summary: t('g.warning'), diff --git a/src/platform/workspace/billing/sdk/billingSdkTestUtils.ts b/src/platform/workspace/billing/sdk/billingSdkTestUtils.ts index 634df21a10f..9418f85b41f 100644 --- a/src/platform/workspace/billing/sdk/billingSdkTestUtils.ts +++ b/src/platform/workspace/billing/sdk/billingSdkTestUtils.ts @@ -119,6 +119,7 @@ export function fakeBillingSdk() { recover: vi.fn(async () => ({ status: 'ok' as const, value: undefined })), wake: vi.fn(), switchPresentation: vi.fn(() => 'unchanged' as const), + reportHostedStepOpened: vi.fn(), reportChallengeStarted: vi.fn(), reportChallengeSettled: vi.fn(), get: (operationId) => snapshot.find((state) => state.id === operationId),