Metrics Platform/JavaScript API
This page provides a guide to using the Metrics Platform JavaScript API for instrument and experiment creators.
Setup
To set up a local development environment for writing instrument code, follow the setup guide for MediaWiki and Metrics Platform. For more context and tooling recommendations, see the introduction to Metrics Platform development.
Create an instrument
Start by creating an instrument. You'll specify:
- the schema that will be used to validate events, and
- the event stream where events will be published.
These values will be used later to submit events.
const instrument = mw.eventLog.newInstrument(
'mediawiki.product_metrics.example', // event stream name
'/analytics/product_metrics/web/base/1.3.0' // schema ID
);
Once you've created an instrument, you can submit an event using either submitClick
or submitInteraction
.
Submit a click event
submitClick
provides a simplified method to submit click events that use the Metrics Platform base schemas. To specify a custom value for action
or to use a custom schema, use submitInteraction
.
Here's an example of an instrument in JavaScript that uses Instrument#submitClick
to submit an event when a user clicks on an interwiki link.
function getInteractionData( jqEvent ) {
const link = jqEvent.target;
return {
action_source: link.href,
action_context: link.title
};
}
// 'a.extiw' will match anchors that have a extiw class. extiw is used for interwiki links.
$( '#content' ).on(
'click',
'a.extiw',
( jqEvent ) => instrument.submitClick( getLinkInteractionData( jqEvent ) )
);
The resulting event:
- by default, includes
action: click
- includes optional interaction data (
action_source
andaction_context
) - is validated against the latest Metrics Platform base schema for web, as set in
newInstrument
- is published to the specified event stream (in this case,
mediawiki.product_metrics.example
), as set innewInstrument
Submit an interaction event
An interaction event is meant to represent a basic interaction with some target or some event occurring. For example, a user hovers over a UI element or an app notifies the server of its current state.
Here's an example of an instrument in JavaScript that uses Instrument#submitInteraction
to submit an event when a user hovers over an interwiki link.
$( '#content' ).on(
'mouseover',
'a.extiw',
( jqEvent ) => instrument.submitInteraction( 'hover', getLinkInteractionData( jqEvent ) )
);
The resulting event:
- includes the specified value of
action
- includes optional interaction data you have provided in
getLinkInteractionData
(action_source
andaction_context
) - is validated against the specified schema (in this case, the Metrics Platform base schema for web), as set in
newInstrument
- is published to the specified event stream (in this case,
mediawiki.product_metrics.example
), as set innewInstrument
Implementation
In the context of MediaWiki frontend development, the JavaScript MPC is provided by the EventLogging extension. It is delivered as part of the ext.eventLogging
ResourceLoader module and its methods are exposed via mw.eventLog.
The JavaScript MPC and stream configurations are both delivered as part of the module and the stream configurations are not fetched again until the user navigates to another page. This minimizes the number of HTTP requests per pageview.
The EventLogging extension maintains a list of streams to be included in the module, $wgEventLoggingStreamNames
, which can be used to minimize the size of the module. When $wgEventLoggingStreamNames
is falsy the JavaScript MPC will not validate whether the destination stream is configured before submitting the event to the destination event service.
Reference
For parameter descriptions and validation rules, see the web schema definition.
mw.eventLog.newInstrument
Create a new Instrument
.
Parameters:
- streamName (string): Name of the event stream where the events should be submitted
- schemaId (string): Name of the schema to validate the event against. To use the base schema for web, use
/analytics/product_metrics/web/base/x.x.x
with the latest version number.
Instrument#isEnabled
Check if the instrument's stream is in sample
Instrument#setInstrumentName
Set the instrument name (it will be added to the event automatically as an interaction data field)
Parameters:
- instrumentName (string): The name of the instrument
Instrument#submitClick
Submit a click event to an event stream for an instrument. The event data must validate against the base schema for web.
Parameters:
- (optional) interactionData (key/value pairs): Additional event data. See the interaction data fields supported by the base schema for web.
Instrument#submitInteraction
Submit an interaction event to an event stream for an instrument. An interaction event represents a basic interaction with some target or an event occurring, such as the performer clicking a UI element or an app notifying the server of its current state.
Parameters:
- action (string): Name of the interaction. For example,
scroll
- (optional) interactionData (key/value pairs): Additional event data. This data must validate against the specified schema. For example, see the interaction data fields supported by the base schema for web.
submit(streamName, eventData)
as a more general function to send events, where eventData
will have to contain the action
and also the interactionData
mw.eventLog.isCurrentUserEnrolled
Checks whether the user is enrolled in a specific experiment
Parameters
- experimentName (string): Name of the experiment
mw.config.get( 'wgMetricsPlatformUserExperiments' );
Global variable, set by the MetricsPlatform extension, that contains experiment enrollment details for the current user according to the following structure:
experiments: struct<
assigned: map<string, string>
enrolled: array<string>,
features: map<string, string>
>