Metrics Platform/How to/Choose your language/Setup for JS

Requirements

First, make sure you have a MediaWiki instance running as a Docker container

For the Javascript library we provide an environment via Fresh

To install:

curl -fsS 'https://gerrit.wikimedia.org/g/fresh/+/23.08.1/bin/fresh-install?format=TEXT' | base64 --decode | python3

Schema work can be also done using this environment because we use npm to build new schemas/fragments

Writing MediaWiki instrumentation code using the EventLogging extension

A Metrics Platform instrument is creating by calling one of the submit API methods provided by the MP library. These methods can take the following arguments:

• streamName, a string, is required.
• schemaId, a string, is optional/required depending on which submit method is used.
• action, a string, is optional/required depending on which submit method is used.
• InteractionData, a group of key/value pairs, is optional. If it's present, each key must be in snake case, using only lowercase letters, digits, and '_', and starting with a lowercase letter.

The available keys that can be used for InteractionData:

• action_subtype
• action_source
• action_context
• element_id
• element_friendly_name
• funnel_name
• funnel_entry_token
• funnel_event_sequence_position

Each value must be a string with the exception of funnel_event_sequence_position which is required to be an integer (this constraint is codified in the definition of common product metrics in the product_event YAML file. If additional types are supported in future, those types will be added there.)

Creating the instrument

To create an instrument in JavaScript, you need to add code that calls one of the submit methods such as mw.eventLog.submitInteraction. The following code will fire events whenever an interwiki link is hovered over.

// 'a.extiw' will match anchors that have a extiw class.  extiw is used for interwiki links.
$( '#content' ).on( 'mouseover', 'a.extiw', function ( jqEvent ) {
	var link = jqEvent.target;
	var linkHoverInteractionData = {
		action_source: link.href,
		action_context: link.title,
	};

    var action = 'extiw.hover';
    var streamName = 'mediawiki.stream_name';
    var schemaId = '/analytics/product_metrics/web/base/1.1.0';
	mw.eventLog.submitInteraction( streamName, schemaId, action, linkHoverInteractionData );
} );

The same example using the submitClick method:

    ...
    var streamName = 'my.stream';
	mw.eventLog.submitClick( streamName, linkHoverInteractionData );
    ...

Now when you hover over a link, Metrics Client method mw.eventLog.submitInteraction or mw.eventLog.submitClick will be called. The Metrics Client will then construct an event and send it to the specified stream. The event will include the two interaction data elements you have provided in linkHoverInteractionData, as well as several contextual attributes that are specified with the stream's declaration (below).

Note that the first part of the event name, extiw, need not correspond to the anchor class. We've chosen to reuse that class name because of its brevity and its familiarity to the developers of this code.

In summary:

• mw.eventLog.submitInteraction needs: (1) the stream name, (2) the schema ID, (3) the action (event name), and (4) the interaction data for the event.
• mw.eventLog.submitClick needs only: (1) the stream name and (2) the interaction data for the event.