Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation to the Tracking package #20595

Merged
merged 5 commits into from
Aug 9, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 122 additions & 0 deletions projects/packages/tracking/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# Jetpack Tracking package

A package containing functionality to track events to the a8c Tracks system

## Usage

There are several ways to track events using this package.

* Ajax: Probably the easiest one. You can simply add a class to a link and it will be tracked or you can make your own ajax call
* PHP: Track an event on the backend
* Tracking pixel: An alternative way to track events by dynamically adding a pixel to the DOM

### Tracking via Ajax

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

Note: Not needed if you are using the Jetpack plugin in the admin context as the script is already loaded by Jetpack.

See `Automattic\Jetpack\Tracking::enqueue_tracks_scripts()`

```PHP
add_action( 'admin_enqueue_scripts', array( new Tracking( 'plugin-slug' ), 'enqueue_tracks_scripts' ) );
```

#### 2. Add the class and the event attributes.

Add the `jptracks` class to any `a` element or to its parent element.

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

```HTML
<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.

**Note:** Event name will be automatically prefixed with `jetpack_`.

#### 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:

```JS
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:

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

### Tracking in PHP

Use `Automattic\Jetpack\Tracking::record_user_event()` to track events on the backend.

```PHP
$connection_manager = new Automattic\Jetpack\Connection\Manager( 'plugin-slug' );
$tracking = new Tracking( 'plugin-slug', $connection_manager );
$tracking->record_user_event(
$event_name,
array(
'property_key' => 'value',
)
);
```

### Tracking pixel

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

```PHP
Tracking::register_tracks_functions_scripts( true );
```

#### 2. Inform the user data

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

#### 3. Track!

In your JS:

```JS
var tracksUser = varname.tracksUserData;

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

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

## Debugging

You can watch your events being tracked in the browser console. In order to activate that, run the following command in the console:

```JS
localStorage.setItem( 'debug', 'dops:analytics*' );
```
4 changes: 4 additions & 0 deletions projects/packages/tracking/changelog/add-tracks-docs
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
Significance: patch
Type: added

adding Readme to the tracking package