diff options
Diffstat (limited to 'plugins/jetpack/_inc/lib/tracks')
| -rw-r--r-- | plugins/jetpack/_inc/lib/tracks/class.tracks-client.php | 191 | ||||
| -rw-r--r-- | plugins/jetpack/_inc/lib/tracks/class.tracks-event.php | 149 | ||||
| -rw-r--r-- | plugins/jetpack/_inc/lib/tracks/client.php | 130 | ||||
| -rw-r--r-- | plugins/jetpack/_inc/lib/tracks/tracks-ajax.js | 62 | ||||
| -rw-r--r-- | plugins/jetpack/_inc/lib/tracks/tracks-callables.js | 76 |
5 files changed, 608 insertions, 0 deletions
diff --git a/plugins/jetpack/_inc/lib/tracks/class.tracks-client.php b/plugins/jetpack/_inc/lib/tracks/class.tracks-client.php new file mode 100644 index 00000000..b83c94f1 --- /dev/null +++ b/plugins/jetpack/_inc/lib/tracks/class.tracks-client.php @@ -0,0 +1,191 @@ +<?php + +/** + * Jetpack_Tracks_Client + * @autounit nosara tracks-client + * + * Send Tracks events on behalf of a user + * + * Example Usage: +```php + require( dirname(__FILE__).'path/to/tracks/class.tracks-client' ); + + $result = Jetpack_Tracks_Client::record_event( array( + '_en' => $event_name, // required + '_ui' => $user_id, // required unless _ul is provided + '_ul' => $user_login, // required unless _ui is provided + + // Optional, but recommended + '_ts' => $ts_in_ms, // Default: now + '_via_ip' => $client_ip, // we use it for geo, etc. + + // Possibly useful to set some context for the event + '_via_ua' => $client_user_agent, + '_via_url' => $client_url, + '_via_ref' => $client_referrer, + + // For user-targeted tests + 'abtest_name' => $abtest_name, + 'abtest_variation' => $abtest_variation, + + // Your application-specific properties + 'custom_property' => $some_value, + ) ); + + if ( is_wp_error( $result ) ) { + // Handle the error in your app + } +``` + */ + +require_once( dirname(__FILE__).'/class.tracks-client.php' ); + +class Jetpack_Tracks_Client { + const PIXEL = 'https://pixel.wp.com/t.gif'; + const BROWSER_TYPE = 'php-agent'; + const USER_AGENT_SLUG = 'tracks-client'; + const VERSION = '0.3'; + + /** + * record_event + * @param mixed $event Event object to send to Tracks. An array will be cast to object. Required. + * Properties are included directly in the pixel query string after light validation. + * @return mixed True on success, WP_Error on failure + */ + static function record_event( $event ) { + if ( ! Jetpack::jetpack_tos_agreed() || ! empty( $_COOKIE['tk_opt-out'] ) ) { + return false; + } + + if ( ! $event instanceof Jetpack_Tracks_Event ) { + $event = new Jetpack_Tracks_Event( $event ); + } + if ( is_wp_error( $event ) ) { + return $event; + } + + $pixel = $event->build_pixel_url( $event ); + + if ( ! $pixel ) { + return new WP_Error( 'invalid_pixel', 'cannot generate tracks pixel for given input', 400 ); + } + + return self::record_pixel( $pixel ); + } + + /** + * Synchronously request the pixel + */ + static function record_pixel( $pixel ) { + // Add the Request Timestamp and URL terminator just before the HTTP request. + $pixel .= '&_rt=' . self::build_timestamp() . '&_=_'; + + $response = wp_remote_get( $pixel, array( + 'blocking' => true, // The default, but being explicit here :) + 'timeout' => 1, + 'redirection' => 2, + 'httpversion' => '1.1', + 'user-agent' => self::get_user_agent(), + ) ); + + if ( is_wp_error( $response ) ) { + return $response; + } + + $code = isset( $response['response']['code'] ) ? $response['response']['code'] : 0; + + if ( $code !== 200 ) { + return new WP_Error( 'request_failed', 'Tracks pixel request failed', $code ); + } + + return true; + } + + static function get_user_agent() { + return Jetpack_Tracks_Client::USER_AGENT_SLUG . '-v' . Jetpack_Tracks_Client::VERSION; + } + + /** + * Build an event and return its tracking URL + * @deprecated Call the `build_pixel_url` method on a Jetpack_Tracks_Event object instead. + * @param array $event Event keys and values + * @return string URL of a tracking pixel + */ + static function build_pixel_url( $event ) { + $_event = new Jetpack_Tracks_Event( $event ); + return $_event->build_pixel_url(); + } + + /** + * Validate input for a tracks event. + * @deprecated Instantiate a Jetpack_Tracks_Event object instead + * @param array $event Event keys and values + * @return mixed Validated keys and values or WP_Error on failure + */ + private static function validate_and_sanitize( $event ) { + $_event = new Jetpack_Tracks_Event( $event ); + if ( is_wp_error( $_event ) ) { + return $_event; + } + return get_object_vars( $_event ); + } + + // Milliseconds since 1970-01-01 + static function build_timestamp() { + $ts = round( microtime( true ) * 1000 ); + return number_format( $ts, 0, '', '' ); + } + + /** + * Grabs the user's anon id from cookies, or generates and sets a new one + * + * @return string An anon id for the user + */ + static function get_anon_id() { + static $anon_id = null; + + if ( ! isset( $anon_id ) ) { + + // Did the browser send us a cookie? + if ( isset( $_COOKIE[ 'tk_ai' ] ) && preg_match( '#^[A-Za-z0-9+/=]{24}$#', $_COOKIE[ 'tk_ai' ] ) ) { + $anon_id = $_COOKIE[ 'tk_ai' ]; + } else { + + $binary = ''; + + // Generate a new anonId and try to save it in the browser's cookies + // Note that base64-encoding an 18 character string generates a 24-character anon id + for ( $i = 0; $i < 18; ++$i ) { + $binary .= chr( mt_rand( 0, 255 ) ); + } + + $anon_id = 'jetpack:' . base64_encode( $binary ); + + if ( ! headers_sent() + && ! ( defined( 'REST_REQUEST' ) && REST_REQUEST ) + && ! ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) + ) { + setcookie( 'tk_ai', $anon_id ); + } + } + } + + return $anon_id; + } + + /** + * Gets the WordPress.com user's Tracks identity, if connected. + * + * @return array|bool + */ + static function get_connected_user_tracks_identity() { + if ( ! $user_data = Jetpack::get_connected_user_data() ) { + return false; + } + + return array( + 'userid' => $user_data['ID'], + 'username' => $user_data['login'], + ); + } +} diff --git a/plugins/jetpack/_inc/lib/tracks/class.tracks-event.php b/plugins/jetpack/_inc/lib/tracks/class.tracks-event.php new file mode 100644 index 00000000..fb86e0ba --- /dev/null +++ b/plugins/jetpack/_inc/lib/tracks/class.tracks-event.php @@ -0,0 +1,149 @@ +<?php + +/** + * @autounit nosara tracks-client + * + * Example Usage: +```php + require_once( dirname(__FILE__) . 'path/to/tracks/class.tracks-event' ); + + $event = new Jetpack_Tracks_Event( array( + '_en' => $event_name, // required + '_ui' => $user_id, // required unless _ul is provided + '_ul' => $user_login, // required unless _ui is provided + + // Optional, but recommended + '_via_ip' => $client_ip, // for geo, etc. + + // Possibly useful to set some context for the event + '_via_ua' => $client_user_agent, + '_via_url' => $client_url, + '_via_ref' => $client_referrer, + + // For user-targeted tests + 'abtest_name' => $abtest_name, + 'abtest_variation' => $abtest_variation, + + // Your application-specific properties + 'custom_property' => $some_value, + ) ); + + if ( is_wp_error( $event->error ) ) { + // Handle the error in your app + } + + $bump_and_redirect_pixel = $event->build_signed_pixel_url(); +``` + */ + +require_once( dirname(__FILE__) . '/class.tracks-client.php' ); + +class Jetpack_Tracks_Event { + const EVENT_NAME_REGEX = '/^(([a-z0-9]+)_){2}([a-z0-9_]+)$/'; + const PROP_NAME_REGEX = '/^[a-z_][a-z0-9_]*$/'; + public $error; + + function __construct( $event ) { + $_event = self::validate_and_sanitize( $event ); + if ( is_wp_error( $_event ) ) { + $this->error = $_event; + return; + } + + foreach( $_event as $key => $value ) { + $this->{$key} = $value; + } + } + + function record() { + return Jetpack_Tracks_Client::record_event( $this ); + } + + /** + * Annotate the event with all relevant info. + * @param mixed $event Object or (flat) array + * @return mixed The transformed event array or WP_Error on failure. + */ + static function validate_and_sanitize( $event ) { + $event = (object) $event; + + // Required + if ( ! $event->_en ) { + return new WP_Error( 'invalid_event', 'A valid event must be specified via `_en`', 400 ); + } + + // delete non-routable addresses otherwise geoip will discard the record entirely + if ( property_exists( $event, '_via_ip' ) && preg_match( '/^192\.168|^10\./', $event->_via_ip ) ) { + unset($event->_via_ip); + } + + $validated = array( + 'browser_type' => Jetpack_Tracks_Client::BROWSER_TYPE, + '_aua' => Jetpack_Tracks_Client::get_user_agent(), + ); + + $_event = (object) array_merge( (array) $event, $validated ); + + // If you want to blacklist property names, do it here. + + // Make sure we have an event timestamp. + if ( ! isset( $_event->_ts ) ) { + $_event->_ts = Jetpack_Tracks_Client::build_timestamp(); + } + + return $_event; + } + + /** + * Build a pixel URL that will send a Tracks event when fired. + * On error, returns an empty string (''). + * + * @return string A pixel URL or empty string ('') if there were invalid args. + */ + function build_pixel_url() { + if ( $this->error ) { + return ''; + } + + $args = get_object_vars( $this ); + + // Request Timestamp and URL Terminator must be added just before the HTTP request or not at all. + unset( $args['_rt'] ); + unset( $args['_'] ); + + $validated = self::validate_and_sanitize( $args ); + + if ( is_wp_error( $validated ) ) + return ''; + + return Jetpack_Tracks_Client::PIXEL . '?' . http_build_query( $validated ); + } + + static function event_name_is_valid( $name ) { + return preg_match( Jetpack_Tracks_Event::EVENT_NAME_REGEX, $name ); + } + + static function prop_name_is_valid( $name ) { + return preg_match( Jetpack_Tracks_Event::PROP_NAME_REGEX, $name ); + } + + static function scrutinize_event_names( $event ) { + if ( ! Jetpack_Tracks_Event::event_name_is_valid( $event->_en ) ) { + return; + } + + $whitelisted_key_names = array( + 'anonId', + 'Browser_Type', + ); + + foreach ( array_keys( (array) $event ) as $key ) { + if ( in_array( $key, $whitelisted_key_names ) ) { + continue; + } + if ( ! Jetpack_Tracks_Event::prop_name_is_valid( $key ) ) { + return; + } + } + } +} diff --git a/plugins/jetpack/_inc/lib/tracks/client.php b/plugins/jetpack/_inc/lib/tracks/client.php new file mode 100644 index 00000000..bd92d272 --- /dev/null +++ b/plugins/jetpack/_inc/lib/tracks/client.php @@ -0,0 +1,130 @@ +<?php +/** + * PHP Tracks Client + * @autounit nosara tracks-client + * Example Usage: + * +```php + include( plugin_dir_path( __FILE__ ) . 'lib/tracks/client.php'); + $result = jetpack_tracks_record_event( $user, $event_name, $properties ); + + if ( is_wp_error( $result ) ) { + // Handle the error in your app + } +``` + */ + +// Load the client classes +require_once( dirname(__FILE__) . '/class.tracks-event.php' ); +require_once( dirname(__FILE__) . '/class.tracks-client.php' ); + +// Now, let's export a sprinkling of syntactic sugar! + +/** + * Procedurally (vs. Object-oriented), track an event object (or flat array) + * NOTE: Use this only when the simpler jetpack_tracks_record_event() function won't work for you. + * @param \Jetpack_Tracks_Event $event The event object. + * @return \Jetpack_Tracks_Event|\WP_Error + */ +function jetpack_tracks_record_event_raw( $event ) { + return Jetpack_Tracks_Client::record_event( $event ); +} + +/** + * Procedurally build a Tracks Event Object. + * NOTE: Use this only when the simpler jetpack_tracks_record_event() function won't work for you. + * @param $identity WP_user object + * @param string $event_name The name of the event + * @param array $properties Custom properties to send with the event + * @param int $event_timestamp_millis The time in millis since 1970-01-01 00:00:00 when the event occurred + * @return \Jetpack_Tracks_Event|\WP_Error + */ +function jetpack_tracks_build_event_obj( $user, $event_name, $properties = array(), $event_timestamp_millis = false ) { + + $identity = jetpack_tracks_get_identity( $user->ID ); + + $properties['user_lang'] = $user->get( 'WPLANG' ); + + $blog_details = array( + 'blog_lang' => isset( $properties['blog_lang'] ) ? $properties['blog_lang'] : get_bloginfo( 'language' ) + ); + + $timestamp = ( $event_timestamp_millis !== false ) ? $event_timestamp_millis : round( microtime( true ) * 1000 ); + $timestamp_string = is_string( $timestamp ) ? $timestamp : number_format( $timestamp, 0, '', '' ); + + return new Jetpack_Tracks_Event( array_merge( $blog_details, (array) $properties, $identity, array( + '_en' => $event_name, + '_ts' => $timestamp_string + ) ) ); +} + +/* + * Get the identity to send to tracks. + * + * @param int $user_id The user id of the local user + * @return array $identity + */ +function jetpack_tracks_get_identity( $user_id ) { + + // Meta is set, and user is still connected. Use WPCOM ID + $wpcom_id = get_user_meta( $user_id, 'jetpack_tracks_wpcom_id', true ); + if ( $wpcom_id && Jetpack::is_user_connected( $user_id ) ) { + return array( + '_ut' => 'wpcom:user_id', + '_ui' => $wpcom_id + ); + } + + // User is connected, but no meta is set yet. Use WPCOM ID and set meta. + if ( Jetpack::is_user_connected( $user_id ) ) { + $wpcom_user_data = Jetpack::get_connected_user_data( $user_id ); + update_user_meta( $user_id, 'jetpack_tracks_wpcom_id', $wpcom_user_data['ID'] ); + + return array( + '_ut' => 'wpcom:user_id', + '_ui' => $wpcom_user_data['ID'] + ); + } + + // User isn't linked at all. Fall back to anonymous ID. + $anon_id = get_user_meta( $user_id, 'jetpack_tracks_anon_id', true ); + if ( ! $anon_id ) { + $anon_id = Jetpack_Tracks_Client::get_anon_id(); + add_user_meta( $user_id, 'jetpack_tracks_anon_id', $anon_id, false ); + } + + if ( ! isset( $_COOKIE[ 'tk_ai' ] ) && ! headers_sent() ) { + setcookie( 'tk_ai', $anon_id ); + } + + return array( + '_ut' => 'anon', + '_ui' => $anon_id + ); + +} + +/** + * Record an event in Tracks - this is the preferred way to record events from PHP. + * + * @param mixed $identity username, user_id, or WP_user object + * @param string $event_name The name of the event + * @param array $properties Custom properties to send with the event + * @param int $event_timestamp_millis The time in millis since 1970-01-01 00:00:00 when the event occurred + * @return bool true for success | \WP_Error if the event pixel could not be fired + */ +function jetpack_tracks_record_event( $user, $event_name, $properties = array(), $event_timestamp_millis = false ) { + + // We don't want to track user events during unit tests/CI runs. + if ( $user instanceof WP_User && 'wptests_capabilities' === $user->cap_key ) { + return false; + } + + $event_obj = jetpack_tracks_build_event_obj( $user, $event_name, $properties, $event_timestamp_millis ); + + if ( is_wp_error( $event_obj->error ) ) { + return $event_obj->error; + } + + return $event_obj->record(); +} diff --git a/plugins/jetpack/_inc/lib/tracks/tracks-ajax.js b/plugins/jetpack/_inc/lib/tracks/tracks-ajax.js new file mode 100644 index 00000000..911275bd --- /dev/null +++ b/plugins/jetpack/_inc/lib/tracks/tracks-ajax.js @@ -0,0 +1,62 @@ +/* global jpTracksAJAX, jQuery */ +( function( $, jpTracksAJAX ) { + window.jpTracksAJAX = window.jpTracksAJAX || {}; + const debugSet = localStorage.getItem( 'debug' ) === 'dops:analytics'; + + window.jpTracksAJAX.record_ajax_event = function( eventName, eventType, eventProp ) { + var data = { + tracksNonce: jpTracksAJAX.jpTracksAJAX_nonce, + action: 'jetpack_tracks', + tracksEventType: eventType, + tracksEventName: eventName, + tracksEventProp: eventProp || false, + }; + + return $.ajax( { + type: 'POST', + url: jpTracksAJAX.ajaxurl, + data: data, + success: function( response ) { + if ( debugSet ) { + // eslint-disable-next-line + console.log( 'AJAX tracks event recorded: ', data, response ); + } + }, + } ); + }; + + $( document ).ready( function() { + $( 'body' ).on( 'click', '.jptracks a, a.jptracks', function( event ) { + var $this = $( event.target ); + // We know that the jptracks element is either this, or its ancestor + var $jptracks = $this.closest( '.jptracks' ); + // We need an event name at least + var eventName = $jptracks.attr( 'data-jptracks-name' ); + if ( undefined === eventName ) { + return; + } + + var eventProp = $jptracks.attr( 'data-jptracks-prop' ) || false; + + var url = $this.attr( 'href' ); + var target = $this.get( 0 ).target; + if ( url && target && '_self' !== target ) { + var newTabWindow = window.open( '', target ); + newTabWindow.opener = null; + } + + event.preventDefault(); + + window.jpTracksAJAX.record_ajax_event( eventName, 'click', eventProp ).always( function() { + // Continue on to whatever url they were trying to get to. + if ( url && ! $this.hasClass( 'thickbox' ) ) { + if ( newTabWindow ) { + newTabWindow.location = url; + return; + } + window.location = url; + } + } ); + } ); + } ); +} )( jQuery, jpTracksAJAX ); diff --git a/plugins/jetpack/_inc/lib/tracks/tracks-callables.js b/plugins/jetpack/_inc/lib/tracks/tracks-callables.js new file mode 100644 index 00000000..d4e53af6 --- /dev/null +++ b/plugins/jetpack/_inc/lib/tracks/tracks-callables.js @@ -0,0 +1,76 @@ +/** + * This was abstracted from wp-calypso's analytics lib: https://github.com/Automattic/wp-calypso/blob/master/client/lib/analytics/README.md + * Some stuff was removed like GA tracking and other things not necessary for Jetpack tracking. + * + * This library should only be used and loaded if the Jetpack site is connected. + */ + +// Load tracking scripts +window._tkq = window._tkq || []; + +function buildQuerystring( group, name ) { + var uriComponent = ''; + + if ( 'object' === typeof group ) { + for ( var key in group ) { + uriComponent += '&x_' + encodeURIComponent( key ) + '=' + encodeURIComponent( group[ key ] ); + } + } else { + uriComponent = '&x_' + encodeURIComponent( group ) + '=' + encodeURIComponent( name ); + } + + return uriComponent; +} + +var analytics = { + initialize: function( userId, username ) { + analytics.setUser( userId, username ); + analytics.identifyUser(); + }, + + mc: { + bumpStat: function( group, name ) { + var uriComponent = buildQuerystring( group, name ); // prints debug info + new Image().src = + document.location.protocol + + '//pixel.wp.com/g.gif?v=wpcom-no-pv' + + uriComponent + + '&t=' + + Math.random(); + }, + }, + + tracks: { + recordEvent: function( eventName, eventProperties ) { + eventProperties = eventProperties || {}; + + if ( eventName.indexOf( 'jetpack_' ) !== 0 ) { + debug( '- Event name must be prefixed by "jetpack_"' ); + return; + } + + window._tkq.push( [ 'recordEvent', eventName, eventProperties ] ); + }, + + recordPageView: function( urlPath ) { + analytics.tracks.recordEvent( 'jetpack_page_view', { + path: urlPath, + } ); + }, + }, + + setUser: function( userId, username ) { + _user = { ID: userId, username: username }; + }, + + identifyUser: function() { + // Don't identify the user if we don't have one + if ( _user ) { + window._tkq.push( [ 'identifyUser', _user.ID, _user.username ] ); + } + }, + + clearedIdentity: function() { + window._tkq.push( [ 'clearIdentity' ] ); + }, +}; |