@automattic/jetpack-shared-extension-utils 0.6.10 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2023-01-02
+### Added
+- Add additional methods to useAnalytics hook, allow for view event by passing initial props [#28072]
+
+## [0.7.0] - 2022-12-19
+### Added
+- Add new Analytics wrapper hook. [#27937]
+- Add new isCurrentUserConnected utility. [#27923]
+
 ## [0.6.10] - 2022-12-06
 ### Changed
 - Updated package dependencies. [#27688, #27696, #27697]]
@@ -144,6 +153,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Core: prepare utility for release
 
+[0.8.0]: https://github.com/Automattic/jetpack-shared-extension-utils/compare/0.7.0...0.8.0
+[0.7.0]: https://github.com/Automattic/jetpack-shared-extension-utils/compare/0.6.10...0.7.0
 [0.6.10]: https://github.com/Automattic/jetpack-shared-extension-utils/compare/0.6.9...0.6.10
 [0.6.9]: https://github.com/Automattic/jetpack-shared-extension-utils/compare/0.6.8...0.6.9
 [0.6.8]: https://github.com/Automattic/jetpack-shared-extension-utils/compare/0.6.7...0.6.8

package/index.js

@@ -13,3 +13,5 @@ export {
 	isStillUsableWithFreePlan,
 	getUsableBlockProps,
 } from './src/plan-utils';
+export { default as isCurrentUserConnected } from './src/is-current-user-connected';
+export { default as useAnalytics } from './src/hooks/use-analytics';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@automattic/jetpack-shared-extension-utils",
-	"version": "0.6.10",
+	"version": "0.8.0",
 	"description": "Utility functions used by the block editor extensions",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/shared-extension-utils/#readme",
 	"bugs": {
@@ -15,7 +15,10 @@
 	"author": "Automattic",
 	"scripts": {},
 	"dependencies": {
+		"@automattic/jetpack-analytics": "workspace:*",
+		"@automattic/jetpack-connection": "workspace:*",
 		"@wordpress/compose": "5.20.0",
+		"@wordpress/element": "4.20.0",
 		"@wordpress/i18n": "4.22.0",
 		"@wordpress/plugins": "4.20.0",
 		"@wordpress/url": "3.23.0",

package/src/hooks/readme.md

@@ -0,0 +1,45 @@
+# useAnalytics() hook
+
+This wrapper for @automattic/jetpack-analytics provides a way to use the analytics library (Tracks) in a React component inside your plugin.
+
+This library is only useful when the logged in user is connected to WordPress.com, and when we have information about that connection passed to JavaScript via the Jetpack Connection package. Typically, this is done by enqueuing the connection package's initial state on the editor page:
+
+```php
+use Automattic\Jetpack\Connection\Initial_State as Connection_Initial_State;
+// Adds Connection package initial state.
+wp_add_inline_script( 'your-app-script-handle-in-editor', Connection_Initial_State::render(), 'before' );
+```
+
+## Usage
+
+```es6
+const { tracks } = useAnalytics();
+
+tracks.recordEvent( 'jetpack_editor_block_upgrade_click', {
+	plan,
+	block: blockName,
+	context,
+} );
+```
+
+The hook function also accepts parameters to record a "page view" event when the component renders.
+You can also import a wrapped version of `recordEvent` that checks for a Jetpack connected user before actually recording the event.  
+
+```es6
+const Component = () => {
+	const { recordEvent } = useAnalytics( {
+			pageViewEventName: 'view_event_name',
+			pageViewNamespace: 'jetpack',
+			pageViewSuffix: '',
+		} );
+	const recordClick = useCallback( () => { recordEvent( 'event_name', {} ) }, [] );
+	
+	return (
+		<Button
+			onClick={ recordClick }
+		>
+			{ __( 'Action Button', 'jetpack' ) }
+		</Button>
+	)
+}
+```

package/src/hooks/use-analytics.js

@@ -0,0 +1,86 @@
+import jetpackAnalytics from '@automattic/jetpack-analytics';
+import { useConnection } from '@automattic/jetpack-connection';
+import { useEffect, useState, useCallback } from '@wordpress/element';
+
+const { tracks } = jetpackAnalytics;
+const { recordEvent } = tracks;
+
+const useAnalytics = ( {
+	pageViewEventName = null,
+	pageViewNamespace = 'jetpack',
+	pageViewSuffix = 'page_view',
+	pageViewEventProperties = {},
+} = {} ) => {
+	const [ pageViewRecorded, setPageViewRecorded ] = useState( false );
+	const { isUserConnected, isRegistered, userConnectionData = {} } = useConnection();
+	const { wpcomUser: { login, ID } = {}, blogId } = userConnectionData.currentUser || {};
+
+	/**
+	 * Record an event async
+	 * Check to ensure there is a connected user first
+	 */
+	const recordEventAsync = useCallback(
+		async ( event, properties = {} ) => {
+			// Do nothing if there is not a connected user.
+			if ( ! ( isUserConnected && ID && login ) ) {
+				return;
+			}
+			recordEvent( event, properties );
+		},
+		[ isUserConnected, ID, login ]
+	);
+
+	/**
+	 * Initialize tracks with user and blog data.
+	 * This will only work if the user is connected.
+	 */
+	useEffect( () => {
+		if ( ! isUserConnected || ! ID || ! login || ! blogId ) {
+			return;
+		}
+
+		jetpackAnalytics.initialize( ID, login, {
+			blog_id: blogId,
+		} );
+	}, [ blogId, ID, login, isUserConnected ] );
+
+	/**
+	 * Track a page-view type event.
+	 * It's considered a page view event when the component is mounted.
+	 */
+	useEffect( () => {
+		const pageViewEvent = pageViewEventName
+			? `${ pageViewNamespace }_${ pageViewEventName }_${ pageViewSuffix }`
+			: null;
+
+		// Also, only run if the site is registered.
+		if ( ! isRegistered ) {
+			return;
+		}
+
+		if ( ! pageViewEvent ) {
+			return;
+		}
+
+		// Ensuring we only record the view event once
+		if ( ! pageViewRecorded ) {
+			recordEventAsync( pageViewEvent, pageViewEventProperties );
+			setPageViewRecorded( true );
+		}
+	}, [
+		pageViewRecorded,
+		pageViewNamespace,
+		pageViewEventName,
+		pageViewSuffix,
+		isRegistered,
+		pageViewEventProperties,
+		recordEventAsync,
+	] );
+
+	return {
+		recordEvent: recordEventAsync,
+		tracks: tracks,
+	};
+};
+
+export default useAnalytics;

package/src/is-current-user-connected.js

@@ -0,0 +1,10 @@
+import getJetpackData from './get-jetpack-data';
+
+/**
+ * Return whether the current user is connected to WP.com.
+ *
+ * @returns {boolean} Whether the current user is connected.
+ */
+export default function isCurrentUserConnected() {
+	return getJetpackData()?.jetpack?.is_current_user_connected ?? false;
+}