STATS-523: Premium Analytics: Offer a paid Stats plan to free sites after 30 days (#53647)

Co-authored-by: Chi-Hsuan Huang <chihsuan.tw@gmail.com>

Author: Nikschavan

projects/packages/premium-analytics/changelog/stats-523-free-site-upgrade-notice

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Offer a paid Stats plan to free sites 30 days after their first visit, and show one Stats notice at a time.

projects/packages/premium-analytics/docs/dashboard-widgets.md

@@ -161,7 +161,7 @@ A rename keeps the attributes as they are. One that changes them needs a migrati
 
 A widget that shows nothing but a paid Stats feature declares that feature in `plan_feature`: in the `$args['plan_features']` map of `register_widget_types_from_manifest()`, or in the arguments of `register_widget_type()`. wp-build drops unknown `widget.json` keys, so the manifest cannot carry it. `register()` refuses one that is not a string. The package declares its own in `WIDGET_TYPE_PLAN_FEATURES`; a widget every plan includes declares none.
 
-`stats-plan-gates.php` owns the features and which plan locks each. On the dashboard it publishes `premium_analytics.plan_gates`: `locked_features` maps each feature the site's plan lacks to its copy (`description`, with `<link>` around the words `support_url` explains) and `upgrade_url`, empty when there is nowhere to buy it, and `locked_widget_types` maps each available type whose feature is locked to that feature. The `jetpack_premium_analytics_stats_plan_tier` filter overrides the tier both come from. Declaring a plan feature needs `WIDGET_API_VERSION` 1.12.0; an older registry ignores it, and the widget stays open.
+`stats-plan-gates.php` owns the features and which plan locks each. On the dashboard it publishes `premium_analytics.plan_gates`: `locked_features` maps each feature the site's plan lacks to its copy (`description`, with `<link>` around the words `support_url` explains) and `upgrade_url`, empty when there is nowhere to buy it, and `locked_widget_types` maps each available type whose feature is locked to that feature. `free_site_upgrade` is the paid plan offer the dashboard banner shows: its `upgrade_url`, and `has_stats_product`, which picks the banner title for a site on the free Stats product. It is `null` unless the tier gets the banner, the site has no Stats PWYW, the site is not on WordPress.com Simple, and the site first opened the dashboard at least 30 days ago. The `jetpack_premium_analytics_stats_plan_tier` filter overrides the tier all three come from. Declaring a plan feature needs `WIDGET_API_VERSION` 1.12.0; an older registry ignores it, and the widget stays open.
 
 The dashboard points a locked type at `LockedWidget` instead of its render module, which it never imports, so the widget requests nothing. A feature locked inside a widget that stays open, like the Regions and Cities of **Top locations**, is the widget's to check: it reads `isStatsFeatureLocked()`, renders `LockedWidget` for that part and skips its request.
 

projects/packages/premium-analytics/packages/data/src/queries/stats-app-notices-query.ts

@@ -9,6 +9,7 @@ export type StatsAppNoticeId =
 	| 'client_paid_plan_purchase_success'
 	| 'commercial_site_upgrade'
 	| 'do_you_love_jetpack_stats'
+	| 'free_site_upgrade'
 	| 'gdpr_cookie_consent'
 	| 'new_stats_feedback'
 	| 'opt_in_new_stats'

projects/packages/premium-analytics/packages/site-sync/src/jetpack-script-data.d.ts

@@ -50,6 +50,8 @@ declare module '@automattic/jetpack-script-data' {
 						open_widget_types: string[];
 					}
 				>;
+				// The paid plan offer the banner shows, or null when the site does not qualify (see docs/dashboard-widgets.md). The URL is empty when there is nowhere to buy it, and `has_stats_product` says whether the site has the free Jetpack Stats product.
+				free_site_upgrade?: { upgrade_url: string; has_stats_product: boolean } | null;
 			};
 			// The Stats purchase this page load returned from checkout with; absent on every other load.
 			purchase_success?: { type: 'paid' | 'free' };

projects/packages/premium-analytics/routes/dashboard/components/dashboard-notices/dashboard-notices.tsx

@@ -0,0 +1,53 @@
+/**
+ * External dependencies
+ */
+import { AnalyticsQueryClientProvider } from '@jetpack-premium-analytics/data';
+/**
+ * Internal dependencies
+ */
+import {
+	FreeSiteUpgradeNotice,
+	useFreeSiteUpgradeNoticeVisibility,
+} from '../free-site-upgrade-notice';
+import { PlanLimitNotice } from '../plan-limit-notice';
+import { hasPurchaseSuccess, PurchaseSuccessNotice } from '../purchase-success-notice';
+import type { JSX } from 'react';
+
+/**
+ * Picks the first notice that applies, in Stats' priority order. A notice waits while a
+ * higher-priority one is still loading, so the reader never sees one replaced by another.
+ *
+ * @return The notice, or nothing.
+ */
+function ConnectedNotices(): JSX.Element | null {
+	const showFreeSiteUpgrade = useFreeSiteUpgradeNoticeVisibility();
+
+	// A checkout return holds the other notices back for the whole load, even once dismissed.
+	if ( hasPurchaseSuccess() ) {
+		return <PurchaseSuccessNotice />;
+	}
+
+	if ( showFreeSiteUpgrade === undefined ) {
+		return null;
+	}
+
+	if ( showFreeSiteUpgrade ) {
+		return <FreeSiteUpgradeNotice />;
+	}
+
+	return <PlanLimitNotice />;
+}
+
+/**
+ * The Stats notices above a section, one at a time. Brings its own query provider,
+ * since the dashboard stage has none.
+ *
+ * @return The notice, or nothing.
+ */
+export function DashboardNotices(): JSX.Element {
+	return (
+		<AnalyticsQueryClientProvider>
+			<ConnectedNotices />
+		</AnalyticsQueryClientProvider>
+	);
+}

projects/packages/premium-analytics/routes/dashboard/components/dashboard-notices/index.ts

@@ -0,0 +1 @@
+export { DashboardNotices } from './dashboard-notices';

projects/packages/premium-analytics/routes/dashboard/components/free-site-upgrade-notice/free-site-upgrade-notice.module.scss

@@ -0,0 +1,3 @@
+.notice {
+	margin-block-end: var(--wpds-dimension-gap-lg);
+}

projects/packages/premium-analytics/routes/dashboard/components/free-site-upgrade-notice/free-site-upgrade-notice.test.tsx

@@ -0,0 +1,260 @@
+/**
+ * External dependencies
+ */
+import analytics from '@automattic/jetpack-analytics';
+import { queryClient } from '@jetpack-premium-analytics/data';
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import apiFetch from '@wordpress/api-fetch';
+import { RegistryProvider } from '@wordpress/data';
+/**
+ * Internal dependencies
+ */
+import { createNoticesRegistry } from '../../../../tests/js/notice-test-utils';
+import { DashboardNotices } from '../dashboard-notices';
+import { resetPlanLimitNoticeForTesting } from '../plan-limit-notice/plan-limit-notice';
+import { resetPurchaseSuccessNoticeForTesting } from '../purchase-success-notice/purchase-success-notice';
+import { resetFreeSiteUpgradeNoticeForTesting } from './free-site-upgrade-notice';
+
+jest.mock(
+	'@automattic/jetpack-analytics',
+	() => jest.requireActual( '../../../../tests/js/analytics-test-utils' ).mockJetpackAnalytics
+);
+jest.mock( '@wordpress/api-fetch', () => jest.fn() );
+
+const mockApiFetch = apiFetch as unknown as jest.Mock;
+const recordEvent = jest.mocked( analytics.tracks.recordEvent );
+
+const UPGRADE_URL = 'https://wordpress.com/checkout/example.com/premium?redirect_to=back';
+
+type Site = {
+	offered?: boolean;
+	upgradeUrl?: string;
+	hasStatsProduct?: boolean;
+	purchaseSuccess?: 'paid' | 'free';
+};
+
+let notices = createNoticesRegistry();
+
+/**
+ * Seeds the script data the banner reads.
+ *
+ * @param site                 - The site to seed.
+ * @param site.offered         - Whether the server offers the site a paid plan.
+ * @param site.upgradeUrl      - Where the server sends the upgrade, empty when there is nowhere to buy it.
+ * @param site.hasStatsProduct - Whether the site has a Jetpack Stats product.
+ * @param site.purchaseSuccess - The checkout this load returned from, if any.
+ */
+function setSite( {
+	offered = true,
+	upgradeUrl = UPGRADE_URL,
+	hasStatsProduct = false,
+	purchaseSuccess,
+}: Site = {} ) {
+	window.JetpackScriptData = {
+		site: {
+			admin_url: 'https://example.com/wp-admin/',
+			host: 'jetpack',
+			wpcom: { blog_id: 123456789 },
+		},
+		premium_analytics: {
+			plan_gates: {
+				tier: 'jetpack-free',
+				locked_features: {},
+				locked_widget_types: {},
+				free_site_upgrade: offered
+					? { upgrade_url: upgradeUrl, has_stats_product: hasStatsProduct }
+					: null,
+			},
+			purchase_success: purchaseSuccess ? { type: purchaseSuccess } : undefined,
+		},
+	} as unknown as typeof window.JetpackScriptData;
+}
+
+/**
+ * Answers the notices and plan usage requests.
+ *
+ * @param state     - The Stats notice visibility state, over a banner WordPress.com reports visible; a dismissal updates it.
+ * @param viewsUsed - This cycle's views against a 10,000 limit.
+ */
+function mockEndpoints( state: Record< string, boolean | undefined > = {}, viewsUsed = 0 ) {
+	let saved = { free_site_upgrade: true, ...state };
+	mockApiFetch.mockImplementation( ( { path, method }: { path: string; method?: string } ) => {
+		if ( path.includes( 'jetpack-stats/usage' ) ) {
+			return Promise.resolve( {
+				current_usage: { views_count: viewsUsed },
+				views_limit: 10000,
+			} );
+		}
+		if ( path.includes( 'notices' ) ) {
+			if ( method === 'POST' ) {
+				saved = { ...saved, free_site_upgrade: false };
+			}
+			return Promise.resolve( saved );
+		}
+		return Promise.reject( new Error( `Unexpected request: ${ path }` ) );
+	} );
+}
+
+/**
+ * Renders the notices and settles their requests.
+ *
+ * @return The render result.
+ */
+async function renderNotices() {
+	const view = render(
+		<RegistryProvider value={ notices.registry }>
+			<DashboardNotices />
+		</RegistryProvider>
+	);
+	await act( () => jest.runAllTimersAsync() );
+	await act( () => jest.runAllTimersAsync() );
+	return view;
+}
+
+describe( 'FreeSiteUpgradeNotice', () => {
+	beforeEach( () => {
+		jest.useFakeTimers();
+		queryClient.clear();
+		resetFreeSiteUpgradeNoticeForTesting();
+		resetPlanLimitNoticeForTesting();
+		resetPurchaseSuccessNoticeForTesting();
+		notices = createNoticesRegistry();
+		recordEvent.mockClear();
+		mockApiFetch.mockReset();
+		setSite();
+	} );
+
+	afterEach( () => {
+		jest.useRealTimers();
+	} );
+
+	it( 'offers the upgrade to a free site 30 days after its first visit', async () => {
+		mockEndpoints();
+
+		const { container } = await renderNotices();
+
+		expect( container ).toHaveTextContent( 'Unlock more Stats with a paid plan' );
+		expect( screen.getByRole( 'link', { name: 'Upgrade' } ) ).toHaveAttribute(
+			'href',
+			UPGRADE_URL
+		);
+	} );
+
+	it( 'keeps only Learn more when the server has nowhere to sell the plan', async () => {
+		setSite( { upgradeUrl: '' } );
+		mockEndpoints();
+
+		await renderNotices();
+
+		expect( screen.queryByText( 'Upgrade' ) ).not.toBeInTheDocument();
+		expect( screen.getByRole( 'link', { name: /Learn more/ } ) ).toBeInTheDocument();
+	} );
+
+	it( 'asks a site on the free Stats product whether it wants more', async () => {
+		setSite( { hasStatsProduct: true } );
+		mockEndpoints();
+
+		const { container } = await renderNotices();
+
+		expect( container ).toHaveTextContent( 'Want to get the most out of Jetpack Stats?' );
+	} );
+
+	it( 'says nothing to a site the server does not offer a paid plan', async () => {
+		setSite( { offered: false } );
+		mockEndpoints();
+
+		const { container } = await renderNotices();
+
+		expect( container ).toBeEmptyDOMElement();
+	} );
+
+	it( 'stays away when the notices omit its state, as they do when WordPress.com fails', async () => {
+		mockEndpoints( { free_site_upgrade: undefined } );
+
+		const { container } = await renderNotices();
+
+		expect( container ).toBeEmptyDOMElement();
+	} );
+
+	it.each( [ 'free_site_upgrade', 'do_you_love_jetpack_stats', 'commercial_site_upgrade' ] )(
+		'stays away once Stats has %s dismissed',
+		async id => {
+			mockEndpoints( { [ id ]: false } );
+
+			const { container } = await renderNotices();
+
+			expect( container ).toBeEmptyDOMElement();
+		}
+	);
+
+	it( 'postpones the banner for ten years when dismissed', async () => {
+		mockEndpoints();
+		const user = userEvent.setup( { advanceTimers: jest.advanceTimersByTime } );
+		const { container } = await renderNotices();
+
+		await user.click( screen.getByRole( 'button', { name: 'Dismiss' } ) );
+		await act( () => jest.runAllTimersAsync() );
+
+		expect( container ).toBeEmptyDOMElement();
+		expect( mockApiFetch ).toHaveBeenCalledWith(
+			expect.objectContaining( {
+				method: 'POST',
+				data: { id: 'free_site_upgrade', status: 'postponed', postponed_for: 315360000 },
+			} )
+		);
+	} );
+
+	it( 'stays in place after a failed dismissal, though the refetch fails too', async () => {
+		mockEndpoints();
+		const user = userEvent.setup( { advanceTimers: jest.advanceTimersByTime } );
+		const { container } = await renderNotices();
+		mockApiFetch.mockRejectedValue( new Error( 'offline' ) );
+
+		await user.click( screen.getByRole( 'button', { name: 'Dismiss' } ) );
+		await act( () => jest.runAllTimersAsync() );
+
+		expect( container ).toHaveTextContent( 'Unlock more Stats with a paid plan' );
+	} );
+
+	it( 'shows instead of the plan limit notice when both apply', async () => {
+		mockEndpoints( {}, 9500 );
+
+		const { container } = await renderNotices();
+
+		expect( container ).toHaveTextContent( 'Unlock more Stats with a paid plan' );
+		expect( container ).not.toHaveTextContent( 'You are nearing your monthly limit' );
+	} );
+
+	it( 'gives way to the thank-you notice when a checkout returns', async () => {
+		setSite( { purchaseSuccess: 'free' } );
+		mockEndpoints( {}, 9500 );
+
+		const { container } = await renderNotices();
+
+		expect( container ).toHaveTextContent( 'Thank you for using Jetpack Stats!' );
+		expect( container ).not.toHaveTextContent( 'Unlock more Stats with a paid plan' );
+		expect( container ).not.toHaveTextContent( 'You are nearing your monthly limit' );
+	} );
+
+	it( 'leaves the plan limit notice in place once dismissed', async () => {
+		mockEndpoints( { free_site_upgrade: false }, 9500 );
+
+		const { container } = await renderNotices();
+
+		expect( container ).toHaveTextContent( 'You are nearing your monthly limit' );
+	} );
+
+	it( 'records one view per page load, though every section tab mounts the notices', async () => {
+		mockEndpoints();
+
+		const { unmount } = await renderNotices();
+		unmount();
+		await renderNotices();
+
+		const views = recordEvent.mock.calls.filter(
+			( [ name ] ) => name === 'jetpack_premium_analytics_free_site_upgrade_notice_view'
+		);
+		expect( views ).toHaveLength( 1 );
+	} );
+} );