[$250] Implement new methods for FullStory tracking

[JS00001]

Coming from this thread: https://expensify.slack.com/archives/C07RXNJDMC5/p1779954128210089

We need to add the following data to FullStory.

User Properties

The following should be tracked using FS.setUserVars(...) from the FullStory/index.ts class

Property Name	Data Type	Description	Triggered When	Example Values
user_type_path	string	Dynamic onboarding/user segmentation path	Whenever user context updates	team_1_10_public
account_type	string	Type of account / plan	Triggered on context update	personal, business
user_status	string	Indicates if user is new or returning	Triggered on page load/session start	new, returning
has_completed_onboarding	boolean	Indicates whether onboarding is completed	Triggered when onboarding state changes	TRUE, FALSE
onb_step	string	Current onboarding or setup stage associated with the user		registration, accounting, completed
user_role	string	Defines workspace/account role	Triggered when role context is relevant	admin, auditor, member
workspace_state	string	Indicates whether user has existing workspaces	Triggered on workspace page load
workspace_count	number	Number of workspaces available	Triggered on workspace state change	0, 1, 3
workspace_member_count	number	Number of members added to the workspace during creation/setup		0
free_trial_end_date	date	Date when the user’s free trial ends		2026-05-31 23:59:59
days_till_trial_end	number	Number of days remaining until free trial expiration		14, -3
free_trial_status	string	Current free trial lifecycle status		active, expiring_soon, expired, expired_last30days
plan_type	string	Account/workspace plan type	Triggered on account/workspace context load	collect, control
paid_member	boolean	Indicates whether user converted to a paid plan		TRUE, FALSE
auth_method	string	Authentication method selected	Triggered on login/signup action	email, google
reg_method	string	Registration/signup method used	Triggered after successful signup	Google signup, email/phone signup
login_status	boolean	Result of login attempt	Triggered after login attempt	success, failure

Events

The following should be tracked using FS.event(...) from the FullStory/index.ts class

Property Name	Data Type	Description	Triggered When	Events	Example Values
screen_name	string	Logical name of the current screen or major UI state	Triggered when screen/view context changes	Page_viewed, Component_viewed, clickable_action, Input_field, Error_message, Search_submitted, Chat_opened	Pages, overlays, modals, side panels, search views
entry_point	string	Source from which the user arrived	Triggered on entry/navigation	Page_viewed, sign_up	Registration flow, login flow, homepage entry
location	string	Broad UI area where interaction occurred	Triggered on interaction/view	Component_viewed, clickable_action, Input_field, Error_message	Header, footer, hero, modal, sidebar, cards
component_name	string	Name of component/container where interaction occurs	Triggered on component interaction	Component_viewed, Component_closed, clickable_action, Input_field, Error_message	Search bar, modal, onboarding form, wallet section
onb_step	string	Current onboarding/setup stage	Triggered when onboarding context changes	Page_viewed, Component_viewed, clickable_action, Input_field, Error_message	Registration, onboarding, setup flows
element_label	string	Label of clicked CTA or selectable item	Triggered on click	clickable_action	Buttons, tiles, links, menu items, search results
checked_box	boolean	Indicates whether box is checked or not	Triggered on checkbox click/state	clickable_action	Any checkbox
toggle_swith_on	boolean	Indicates whether the toggle is switched on or off	Triggered on toggle switch interaction	clickable_action	Any toggle switch field
result_type	string	Type/category of the search result item	Triggered on search interaction	clickable_action, Search_submitted	Search results, recent searches, reports, chats
input_field_name	string	Name of interacted input field	Triggered on field interaction	Input_field	Search bars, login fields, forms, chat input
input_field_type	string	Type of input field	Triggered on field interaction	Input_field	Text input, dropdown, checkbox, toggle
input_field_status	string	Current interaction state of input	Triggered when input state changes	Input_field	Focus, typing, cleared, selected
action_status	string	Outcome of action or submission	Triggered after meaningful action completes	clickable_action, Login_submitted, sign_up	Save, submit, verify, enable actions
upload_success	boolean	Indicates upload result	Triggered after upload completes	File_upload_completed	Receipt uploads, attachments, profile uploads
error_location	string	UI location where error occurred	Triggered when error appears	Error_message	Forms, modals, search bar, chat input
error_code	string	System-generated error code	Triggered on backend/system error	Error_message	Authentication, upload, validation flows
error_message	string	Error message displayed to user	Triggered when error appears	Error_message	Validation messages, server errors
error_type	string	Type/category of error	Triggered when error appears	Error_message, Chatbot_response_received	Validation, network, authentication, timeout
search_results_count	number	Number of returned search results	Triggered after search submission	Search_submitted	Global search, inbox search
search_type	string	Type/category of search results	Triggered after search submission	Search_submitted	Chats, reports, mixed results
chat_type	string	Defines how chat is displayed	Triggered when chat opens	Chat_opened	Full-page chat, side-panel chat
has_attachment	boolean	Indicates whether message/upload contains attachment	Triggered when attachment exists	Concierge_message_sent	Chat attachments, uploads
attachment_count	number	Number of attached files	Triggered after attachment added	Concierge_message_sent	Chat uploads, receipt uploads
attachment_types	string	Types of attached files	Triggered after attachment added	Concierge_message_sent	PDFs, images, spreadsheets
upload_method	string	Method used to upload file	Triggered on upload interaction	File_upload_started, Concierge_message_sent	Drag-drop, file picker, camera
position	number	Position of clicked item within list/ranking	Triggered on item click	clickable_action	Search results, dropdowns, ranked lists
expense_type	string	Type/category of created expense		Expense_created	receipt, distance, manual
expense_creation_method	string	Method used to create the expense		Expense_created	manual, scan, import
amount_range	string	Bucketed range of expense amount		Expense_created	0_50, 50_200
expense_count	number	Number of expenses included in a report		Report_created, Report_submitted	4
report_type	string	Type/category of report		Report_created, Report_submitted	expense, invoice, trip
approver_count	number	Number of approvers associated with a report		Report_submitted	2
bank_account_type	string	Type/category of connected bank account		Bank_account_added	personal, business
card_connection_method	string	Method used to connect a bank account or card		Bank_account_added, Card_added	plaid, manual, wallet_import
bank_region	string	Region/country of connected bank account		Bank_account_added	US, EU
card_type	string	Type/category of added payment card		Card_added	virtual, physical, personal
card_provider	string	Provider/network of the added card		Card_added	Visa, Mastercard
card_country	string	Country/region associated with the card		Card_added	US, UK

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022060053526382369725
• Upwork Job ID: 2060053526382369725
• Last Price Increase: 2026-05-28

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @abdulrahuman5196 (External)

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~022060053526382369725

[yuvrajangadsingh]

Proposal

Please re-state the problem that we are trying to solve in this issue.

We need to wire up FS.setUserVars() and FS.event() calls to the correct places in the codebase so FullStory receives the user properties (plan type, trial status, onboarding state, workspace counts, etc.) and interaction events (login, page views, search, expense creation, chat opens, uploads, etc.) listed in the issue.

What is the root cause of that problem?

Both setUserVars and event are already implemented in src/libs/Fullstory/index.ts and src/libs/Fullstory/index.native.ts, and typed in src/libs/Fullstory/types.ts. The gap is that nothing in the app actually calls them with the business-level properties the issue lists. The plumbing exists, the data sources exist, but nobody connects them.

For user properties, all the raw data is already in Onyx: ONYXKEYS.USER_METADATA carries planType, paidMember, freeTrialEndDate, freeTrialStartDate; ONYXKEYS.NVP_ONBOARDING carries hasCompletedGuidedSetupFlow and signupQualifier (the user_type_path); ONYXKEYS.COLLECTION.POLICY carries workspace count and plan type; ONYXKEYS.LOGIN_LIST shows whether the user signed in with Google or email. The code to derive user role from policies already exists in src/libs/telemetry/TelemetrySynchronizer.ts:145-153.

What changes do you think we should make in order to solve the problem?

The main addition is src/libs/Fullstory/FullStorySynchronizer.ts, mirroring src/libs/telemetry/TelemetrySynchronizer.ts exactly. It uses Onyx.connectWithoutView to watch the relevant keys outside the render loop and calls FS.setUserVars() whenever any of them change:

// src/libs/Fullstory/FullStorySynchronizer.ts
import type {OnyxCollection, OnyxEntry} from 'react-native-onyx';
import Onyx from 'react-native-onyx';
import {differenceInDays, parseISO} from 'date-fns';
import {getActivePolicies, isControlPolicy} from '@libs/PolicyUtils';
import FS from '@libs/Fullstory';
import CONST from '@src/CONST';
import ONYXKEYS from '@src/ONYXKEYS';
import type {Policy, Session, UserMetadata, LoginList} from '@src/types/onyx';
import type Onboarding from '@src/types/onyx/Onboarding';

let userMetadata: OnyxEntry<UserMetadata>;
let onboarding: OnyxEntry<Onboarding>;
let policies: OnyxCollection<Policy>;
let session: OnyxEntry<Session>;
let loginList: OnyxEntry<LoginList>;

function getFreeTrialStatus(endDate?: string): string | undefined {
    if (!endDate) return undefined;
    const days = differenceInDays(parseISO(endDate), new Date());
    if (days > 7) return 'active';
    if (days >= 0) return 'expiring_soon';
    if (days >= -30) return 'expired_last30days';
    return 'expired';
}

function sync() {
    if (!userMetadata?.accountID) return;
    const activePolicies = getActivePolicies(policies ?? {}, session?.email);
    const workspaceCount = activePolicies.length;

    let userRole = CONST.POLICY.ROLE.USER;
    for (const p of Object.values(policies ?? {})) {
        if (p?.role === CONST.POLICY.ROLE.ADMIN) { userRole = CONST.POLICY.ROLE.ADMIN; break; }
        if (p?.role === CONST.POLICY.ROLE.AUDITOR) userRole = CONST.POLICY.ROLE.AUDITOR;
    }

    const planType = activePolicies.some(isControlPolicy) ? 'control' : activePolicies.length ? 'collect' : undefined;
    const freeTrialEnd = userMetadata.freeTrialEndDate;
    const daysUntilEnd = freeTrialEnd ? differenceInDays(parseISO(freeTrialEnd), new Date()) : undefined;
    const authMethod = Object.values(loginList ?? {}).some((l) => l?.partnerName === 'google.com') ? 'google' : 'email';

    FS.setUserVars({
        user_type_path: onboarding?.signupQualifier,
        account_type: userMetadata.planType,
        user_status: onboarding?.hasCompletedGuidedSetupFlow ? 'returning' : 'new',
        has_completed_onboarding: onboarding?.hasCompletedGuidedSetupFlow ?? false,
        user_role: userRole,
        workspace_state: workspaceCount > 0 ? 'has_workspaces' : 'no_workspaces',
        workspace_count: workspaceCount,
        free_trial_end_date: freeTrialEnd,
        days_till_trial_end: daysUntilEnd,
        free_trial_status: getFreeTrialStatus(freeTrialEnd),
        plan_type: planType,
        paid_member: userMetadata.paidMember ?? false,
        auth_method: authMethod,
    });
}

Onyx.connectWithoutView({ key: ONYXKEYS.USER_METADATA, callback: (v) => { userMetadata = v; sync(); } });
Onyx.connectWithoutView({ key: ONYXKEYS.NVP_ONBOARDING, callback: (v) => { onboarding = v; sync(); } });
Onyx.connectWithoutView({ key: ONYXKEYS.COLLECTION.POLICY, waitForCollectionCallback: true, callback: (v) => { policies = v; sync(); } });
Onyx.connectWithoutView({ key: ONYXKEYS.SESSION, callback: (v) => { session = v; sync(); } });
Onyx.connectWithoutView({ key: ONYXKEYS.LOGIN_LIST, callback: (v) => { loginList = v; sync(); } });

Then import it as a side-effect in src/Expensify.tsx alongside the existing telemetry import, same line as TelemetrySynchronizer:

import '@libs/Fullstory/FullStorySynchronizer';

For events: src/libs/Navigation/NavigationRoot.tsx already calls new FS.Page(focusedRouteName, ...).start() on route change. Extend that to also call FS.event('Page_viewed', {screen_name: focusedRouteName, entry_point: currentPath}) right alongside it.

Login events go in src/libs/actions/Session/index.ts. After a successful Authenticate API call add FS.event('Login_submitted', {action_status: 'success', auth_method: ...}) and on failure add the same event with action_status: 'failure'. For signup, fire FS.event('sign_up', {reg_method: ...}) after the sign-up API call resolves successfully. The Google sign-in path already branches in the session action so auth_method can be passed at the call site.

For domain-specific events (expense created, report submitted, bank account/card added, search submitted, file upload), add FS.event(...) calls in the corresponding action files: src/libs/actions/IOU.ts for expense and report events, src/libs/actions/BankAccounts.ts and src/libs/actions/Card.ts for bank/card events, the search action for Search_submitted. Each call passes only the properties relevant to that event type as listed in the issue table.

workspace_member_count and onb_step require slightly more context than what's directly on Onyx keys used above. workspace_member_count should read from policy.employeeList size when a workspace is being created (fire FS.setUserVars({workspace_member_count: ...}) from the createWorkspace action in src/libs/actions/Policy/Policy.ts). For onb_step, call FS.setUserVars({onb_step: currentStep}) from the onboarding flow actions in src/libs/actions/Welcome/OnboardingFlow.ts where steps are already tracked.

Conventions copied: Onyx.connectWithoutView aggregation pattern and the userRole derivation loop from src/libs/telemetry/TelemetrySynchronizer.ts:18-160.

What alternative solutions did you explore? (Optional)

I considered hooking everything through FullstoryInitHandler.tsx since it already subscribes to USER_METADATA via useOnyx. That would work for the subset of properties derivable from USER_METADATA alone, but the onboarding, policy, and login-list data would require adding more useOnyx calls to a component that renders null, making it a hidden grab-bag. The Onyx.connectWithoutView approach in a separate synchronizer file is the established pattern for this exact use case, keeps the render tree clean, and lets the data from multiple keys be batched before calling setUserVars once.

[KJ21-ENG]

Proposal

Please re-state the problem that we are trying to solve in this issue.

We need to send the new FullStory user properties and product events listed in the issue from NewDot, using the existing FullStory integration instead of adding one-off SDK calls throughout the app.

What is the root cause of that problem?

The FullStory wrappers already expose the low-level APIs: web calls trackEvent and setProperties through FS.event() / FS.setUserVars(), and native calls FullStory.event() / FullStory.setUserVars().

App/src/libs/Fullstory/index.ts

Lines 105 to 126 in eaaffe3

	event: (eventName, eventProperties = {}) => {
	if (!isInitialized()) {
	return;
	}
	FullStory(CONST.FULLSTORY.OPERATION.TRACK_EVENT, {name: eventName, properties: eventProperties});
	},
	log: (level, message) => {
	if (!isInitialized()) {
	return;
	}
	// Browser SDK doesn't support log levels the same way as native SDK
	// The level parameter is kept for API consistency across platforms
	FullStory('log', {msg: message});
	},
	setUserVars: (userVars) => {
	if (!isInitialized()) {
	return;
	}
	FullStory(CONST.FULLSTORY.OPERATION.SET_PROPERTIES, {type: 'user', properties: userVars});
	},

App/src/libs/Fullstory/index.native.ts

Lines 60 to 75 in eaaffe3

	event: (eventName, eventProperties = {}) => {
	FullStory.event(eventName, eventProperties);
	},
	log: (level, message) => {
	const logLevelMap = {
	log: FullStory.LogLevel.Log,
	info: FullStory.LogLevel.Info,
	warn: FullStory.LogLevel.Warn,
	error: FullStory.LogLevel.Error,
	};
	FullStory.log(logLevelMap[level] ?? FullStory.LogLevel.Log, message);
	},
	setUserVars: (userVars) => {
	FullStory.setUserVars(userVars);

But there is no app-level tracking layer that converts Onyx/user/workspace/onboarding state into the requested FullStory user vars. FullstoryInitHandler only subscribes to ONYXKEYS.USER_METADATA, initializes/identifies FullStory, and stores the session URL in Sentry.

App/src/FullstoryInitHandler.tsx

Lines 13 to 24 in eaaffe3

	function FullstoryInitHandler() {
	const [userMetadata] = useOnyx(ONYXKEYS.USER_METADATA);
	useEffect(() => {
	FS.init(userMetadata);
	FS.getSessionURL().then((url) => {
	if (!url) {
	return;
	}
	Sentry.setContext(CONST.TELEMETRY.CONTEXT_FULLSTORY, {url});
	});
	}, [userMetadata]);

There is also only generic page tracking in navigation, with no standardized event names or property schema for component clicks, input status, searches, uploads, chat opens, expenses, reports, banks, or cards.

App/src/libs/Navigation/NavigationRoot.tsx

Lines 89 to 93 in eaaffe3

	// Fullstory Page navigation tracking
	const focusedRouteName = focusedRoute?.name;
	if (focusedRouteName) {
	new FS.Page(focusedRouteName, {path: currentPath}).start();
	}

Some of the needed values already exist in app state, but they are spread across different models: UserMetadata has planType, trial dates, and paidMember; onboarding has hasCompletedGuidedSetupFlow and signupQualifier; policies have workspace role, type, and member lists.

App/src/types/onyx/UserMetadata.ts

Lines 1 to 32 in eaaffe3

	/** Model of user metadata */
	type UserMetadata = {
	/** Type of user plan */
	planType?: string;
	/** Type of user role */
	role?: string;
	/** Whether the user is on a free trial */
	freeTrial?: boolean;
	/** User's account ID */
	accountID?: number;
	/** User email so we can filter out certain accounts */
	email?: string;
	/** Type of environment the user is using (staging or production) */
	environment?: string;
	/** Information if user dismissed the try new dot popup before. Can be "empty", true or false */
	tryNewDotDismissed?: 'empty' | boolean;
	/** Start date of the user's trial, if existing */
	freeTrialStartDate?: string;
	/** End date of the user's trial, if existing */
	freeTrialEndDate?: string;
	/** Information if the user is a paid member in any policy they're part of */
	paidMember?: boolean;
	};

App/src/types/onyx/Onboarding.ts

Lines 4 to 13 in eaaffe3

	/** Model of onboarding */
	type Onboarding = {
	/** ID of the report used to display the onboarding checklist message */
	chatReportID?: string;
	/** A Boolean that informs whether the user has completed the guided setup onboarding flow */
	hasCompletedGuidedSetupFlow: boolean;
	/** A string that informs which qualifier the user selected during sign up */
	signupQualifier: ValueOf<typeof CONST.ONBOARDING_SIGNUP_QUALIFIERS>;

App/src/types/onyx/Policy.ts

Lines 1998 to 2004 in eaaffe3

	/** The current user's role in the policy */
	role: ValueOf<typeof CONST.POLICY.ROLE>;
	/** The policy type */
	type: ValueOf<typeof CONST.POLICY.TYPE>;

What changes do you think we should make in order to solve the problem?

Add a typed FullStory tracking module under src/libs/Fullstory/ that owns:

• the allowed user-var keys from the issue;
• the allowed event names and event-property keys from the issue;
• small helpers for derived values such as workspace_count, workspace_member_count, workspace_state, account_type, plan_type, user_role, days_till_trial_end, and free_trial_status;
• wrapper methods that call FS.setUserVars() and FS.event() only after filtering out undefined values.

Then add a root-level, renderless handler beside FullstoryInitHandler that subscribes to the needed Onyx keys (USER_METADATA, NVP_ONBOARDING, policies, active policy, trial NVPs, session/account as needed) and updates FullStory user vars when those inputs change. Keep user identity initialization in FullstoryInitHandler; this new handler should only send the additional segmentation/user-context properties.

For event tracking, add exported helpers such as trackFullStoryPageViewed, trackFullStoryClickableAction, trackFullStoryInputField, trackFullStorySearchSubmitted, trackFullStoryChatOpened, trackFullStoryFileUploadCompleted, trackFullStoryExpenseCreated, trackFullStoryReportSubmitted, trackFullStoryBankAccountAdded, and trackFullStoryCardAdded. Wire them at existing action boundaries instead of inside the SDK wrapper itself:

• navigation/page transitions can enrich the existing FS.Page call with a Page_viewed event;
• login/signup status belongs in Session actions and Google/Apple/email entry points;
• search events belong in the search submit/result handlers;
• upload events belong in attachment/receipt upload completion paths;
• expense/report events belong in IOU/report creation and submission actions;
• bank/card events belong in reimbursement/payment-card/company-card completion actions.

This keeps the platform-specific FullStory code unchanged, centralizes the naming contract, and makes each trigger point pass only the context it actually owns.

What alternative solutions did you explore? (Optional)

I would not add raw FS.event() calls directly across every screen. That would technically work, but it would make typos like the requested toggle_swith_on field, date formatting, omitted undefined values, and event/property reuse hard to review. A typed helper layer gives reviewers one place to verify the FullStory schema while keeping the actual triggers close to the product actions.

[github-actions]

⚠️ @KJ21-ENG Your proposal is a duplicate of an already existing proposal and has been automatically withdrawn to prevent spam. Please review the existing proposals before submitting a new one.

[melvin-bot]

📣 @moxw! 📣
Hey, it seems we don’t have your contributor details yet! You'll only have to do this once, and this is how we'll hire you on Upwork.
Please follow these steps:

1. Make sure you've read and understood the contributing guidelines.
2. Get the email address used to login to your Expensify account. If you don't already have an Expensify account, create one here. If you have multiple accounts (e.g. one for testing), please use your main account email.
3. Get the link to your Upwork profile. It's necessary because we only pay via Upwork. You can access it by logging in, and then clicking on your name. It'll look like this. If you don't already have an account, sign up for one here.
4. Copy the format below and paste it in a comment on this issue. Replace the placeholder text with your actual details.
   
   Format:

Contributor details
Your Expensify account email: <REPLACE EMAIL HERE>
Upwork Profile Link: <REPLACE LINK HERE>

[github-actions]

⚠️ @moxw Your proposal is a duplicate of an already existing proposal and has been automatically withdrawn to prevent spam. Please review the existing proposals before submitting a new one.