Tracking Package / tools: consolidate and document available tools

[jeherve]

As I am reviewing Tracks PRs, it makes me realize that we should probably do an iteration on some of those libs, to consolidate things and ensure everything is well documented and that the Tracking package has all the info one would need to use it.

We currently have quite a few solutions available to contributors:

• _inc/client/lib/analytics/ for the React dashboard. Maybe we should work with the Calypso team to move to using a package from the Calypso monorepo if possible. That would ensure we get the latest fixes and enhancements made to that tool. As far as I can tell Calypso's implementation is not a package yet (although we have Calypso Analytics), but I see that @sgomes has been working on the lib lately, so he may have some insight there.
• _inc/lib/tracks/tracks-callables.js for a port of the React implementation.
• _inc/lib/tracks/tracks-ajax.js for the Ajax implementation used in the Tracking package (maybe the lib should be part of the package?).
• src/class-tracking.php for the implementation of the Tracking package within the Jetpack plugin.

None of those solutions are really well documented, so this can be a bit confusing. Maybe we could revisit this and look at all uses of Tracking within the plugin to ensure every feature uses the correct solution.

[sgomes]

Hey @jeherve 👋

My work on lib/analytics has mostly been to make it less of a monolith. We were loading all of it upfront, when some of the largest features were only used in a few places. The work I did can certainly make it easier to move more of it into external packages, though!

@roo2 was doing most of the work in taking pieces out of lib/analytics and moving them to @calypso/analytics, I believe. Perhaps he'll be able to offer further insight?

In any case, I'm happy to help where I can!

[leogermani]

None of those solutions are really well documented, so this can be a bit confusing. Maybe we could revisit this and look at all uses of Tracking within the plugin to ensure every feature uses the correct solution.

Since @dereksmart and I worked on this and struggled to find out how to use these libs, I thought it would be a good idea to document it here how to use them (and then move it to the right place once we decide it)

Tracks Ajax

_inc/lib/tracks/tracks-ajax.js

This is useful to track simple click events without the need of any additional js. Just add the appropriate class to your links and it will be tracked.

1. enqueue script (no need)

The required script is already loaded, at least in admin context. See Automattic\Jetpack\Tracking::enqueue_tracks_scripts()

2. Add the class and the event attributes.

Add the jptracks class to any aelement or to its parent element.

The event needs a name. This can be informed with the data-jptracks-name attritbute.

<a class="jptracks" data-jptracks-name="my-awesome-event">Click me</a>

And that's it. Your event will be tracked. Every time this element is clicked an ajax call will be triggered to the Tracking package and it will send it to wpcom.

3. Additional parameters

You can also inform additional parameters to your event using the data-jptracks-prop attribute. Anything in this attr will be stored in the clicked attribute in the event.

4. Making your own ajax calls

In your JS you can set up your own ajax calls. Example:

window.jpTracksAJAX.record_ajax_event( 'my_event_name', 'click', { prop1: value1, prop2: value2 } );

Note: Event name will be automatically prefixed with jetpack_.

Waiting for the ajax call to complete before doing anything else

If you need to do a subsequent action but wants to wait for this event to be tracked, you can do the following:

window.jpTracksAJAX
	.record_ajax_event( 'my_event_name', 'click', { prop1: value1, prop2: value2 }  )
	.always( function() {
		// do something
	} );

Tracks callable

_inc/lib/tracks/tracks-callables.js

This approach to track events uses //stats.wp.com/w.js and dynamically adds a tracking pixel to the DOM to do the tracking.

1. Enqueue the scripts

Note: We might change this so you don't need to register the scripts every time, and instead just add this as a dependency on your own. I'll came back here and update once we do so.

wp_register_script(
	'jp-tracks',
	'//stats.wp.com/w.js',
	array(),
	gmdate( 'YW' ),
	true
);

wp_register_script(
	'jp-tracks-functions',
	plugins_url( '_inc/lib/tracks/tracks-callables.js', JETPACK__PLUGIN_FILE ),
	array( 'jp-tracks' ),
	JETPACK__VERSION,
	false
);

wp_enqueue_script( 'my_script', 'my-script.js', array( 'jp-tracks-functions' ) );

2. Inform the user data

wp_localize_script(
	'my_script',
	'varname',
	array(
		'tracksUserData'   => Jetpack_Tracks_Client::get_connected_user_tracks_identity(),
	)
);

Track!

var tracksUser = varname.tracksUserData;

analytics.initialize( tracksUser.userid, tracksUser.username );

analytics.tracks.recordEvent( 'jetpack_my_event_name', { prop1: value1, prop2: value2 } );

[roo2]

Hey I was the original one to break out the calypso-analytics library and can give you some context on that. We originally created it in order to add analytics to gutenboarding which is in effect a standalone react app. Original PR

Currently as you may have seen, here's what I think are the pro's and con's of using calypso analytics for jetpack:

Pro:

• It achieves the same thing that jetpack's _inc/client/lib/analytics/ does ( for tracks)
• Has handling for Tracks being blocked by an adblocker
• Manages info about the current user and sends that to tracks
• Using it would make it clear that jetpack analytics works in the same way as calypso's so we could share knowledge/documentation etc

Con:

• Currently Only supports tracks
• Currently hascalypso_ hardcoded into it, whereas you would need to prefix events with jetpack_ etc
• Does some things that jetpack doesn't need like raising events
• Has different debugging messages ( which actually could be consolidated anyway 🤔 )

It looks to me like expanding calypso-analytics to work for jetpack too would be useful, but it won't quite be a drop in replacement without a bit of work.