Metrics Platform/PHP API

This page provides a guide to using the Metrics Platform PHP API for instrument and experiment creators.

Quickstart

Example patch: gerrit:1017961

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.

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 that uses EventLogging::getMetricsPlatformClient()->submitClick() to submit an event when a user clicks on an interwiki link.

$interactionData = [
	'action_source' => 'value for action source',
	'action_context' => 'value for action context'
];

$streamName = 'mediawiki.product_metrics.example_click';
EventLogging::getMetricsPlatformClient()->submitClick( $streamName, $interactionData );

The resulting event:

• by default, includes action: click
• by default, is validated against the latest Metrics Platform base schema for web
• includes optional interaction data you have provided in interactionData. (See the interaction data fields supported by the base schema for web)
• is published to the specified event stream (in this case, mediawiki.product_metrics.example_click)

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 that uses EventLogging::getMetricsPlatformClient()->submitInteraction() to submit an event when a user hovers over an interwiki link.

$interactionData = [
    'action_source' => 'value for action source',
	'action_context' => 'value for action context'
];

$streamName = 'mediawiki.product_metrics.example_hover';
$action = 'hover';
$schemaID = '/analytics/product_metrics/web/base/1.3.0';

EventLogging::getMetricsPlatformClient()->submitInteraction( $streamName, $schemaID, $action, $interactionData );

The resulting event:

• includes the specified value of action
• includes optional interaction data you have provided in interactionData. This data must validate against the specified schema (See the interaction data fields supported by the base schema for web)
• is validated against the specified schema (in this case, the Metrics Platform base schema for web)
• is published to the specified event stream (in this case, mediawiki.product_metrics.example_hover)

Implementation

The PHP MPC is provided by the the EventLogging extension. Its methods are exposed via MediaWiki\Extension\EventLogging\EventLogging.

Like the JavaScript MPC, when $wgEventLoggingStreamNames is falsy the PHP MPC will not validate whether the destination stream is configured before submitting the event to the destination event service.

The PHP MPC does not support sampling by pageview ID or session ID because they are not known to the server (i.e., the PHP layer of MediaWiki). Sampling support can be added if and when there is a use case for it and an appropriate sampling unit defined.

Reference

submitClick

Submit a click event to an event stream. The event data must validate against the base schema for web.

Parameters:

• streamName (string): Name of the event stream where the event should be submitted. Validated against the available event streams.
• (optional) interactionData (array): Additional event data. This data must validate against the base schema for web. See the interaction data fields supported by the base schema for web.

submitInteraction

Submit an interaction event to an event stream. 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:

• streamName (string): Name of the event stream where the event should be submitted. Validated against the available event streams.
• schemaId (string): Name of the schema to validate the event against. For example, to use the base schema for web, use /analytics/product_metrics/web/base/x.x.x using the latest version number.
• action (string): Name of the interaction. For example, scroll
• (optional) interactionData (array): 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.