Metrics Platform/Java API

This page provides a guide to using the Metrics Platform Java 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.

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 submits an event when a user clicks on an interwiki link by instantiating a MetricsClient object and invoking MetricsClient::submitClick.

// Parameters derived from client at instantiation of the Metrics Client object with options to pass in dynamic arguments at the time of event submission
ClientData clientData = new ClientData(
   agentData,
   pageData,
   mediawikiData,
   performerData,
);
InteractionData interactionData = new InteractionData(
   'action_value',
   'action_subtype_value',
   'action_source_value',
   'action_context_value',
);

metricsClient.submitClick(clientData, interactionData);

The resulting event:

by default, includes action: click
includes optional interaction data (action_subtype, action_source, and action_context)
by default, is validated against the latest Metrics Platform base schema for mobile apps
is published to the specified event stream

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 submits an event when a user hovers over an interwiki link by instantiating instantiate a MetricsClient object and invoking MetricsClient::submitInteraction.

Map<String, Object> customData = new HashMap<String, Object>();
customData.put("font_size", "small");
customData.put("is_full_width", true);
customData.put("screen_size", 1080);

metricsClient.submitInteraction(
   "custom_schema_id",
   "some_prefix.some_event_name",
   clientData,
   interactionData,
   customData
);

The resulting event:

includes the specified value of action
includes optional interaction data you have provided in interactionData
is validated against the specified schema (in this case, the Metrics Platform base schema for apps)
is published to the specified event stream

Implementation

The Java MPC is a standalone library that requires the instantiation of a MetricsClient object, which accepts an instance of ClientMetadata in its constructor. The ClientMetadata instance must provide app-specific getters for the values of contextual attributes. These values are submitted along with whatever custom data is passed into submitMetricsEvent. The nested class method Builder.build of the enclosing MetricsClient class is responsible for instantiating an EventProcessor, a MetricsClient, and for fetching stream configurations.

Stream configurations are fetched periodically, with frequency defined by streamConfigFetchInterval in class MetricsClient, which also periodically processes the submission of queued events to the destination event intake service. If stream configurations are not yet available, queued events are held temporarily in the event queue (input buffer) per available space (as allocated in eventQueue's definition in MetricsClient, which can be overridden using method eventQueueCapacity).

If the event queue is full, events are dropped from the queue with a logged warning (from MetricsClient method submit). The metrics client will continue to send queued events to the destination event service at regular intervals (defined by sendEventsInterval). Successfully submitted events are removed from the event queue. Failed event submissions produce an error and remain in the event queue to be retried on the next queued events submission attempt.

Reference

`submitClick`

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

Parameters:

streamName (string): Name of the event stream where the event should be submitted
(optional) clientData (object): Client context data, such as agent, page, MediaWiki, and performer data
(optional) customData (object): Custom data for the interaction. Intended for use with custom schemas. Data included here must validate against the specified schema
(optional) interactionData (object): Additional event data. See the interaction data fields supported by the base schema for apps.
(optional) schemaId (string): Name of the schema to validate the event against. Defaults to the base schema for apps

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

eventName (string): Name of the interaction to populate the action field in the event data. For example, scroll
streamName (string): Name of the event stream where the event should be submitted
(optional) clientData (object): Client context data, such as agent, page, MediaWiki, and performer data
(optional) customData (object): Custom data for the interaction. Intended for use with custom schemas. This data must validate against the specified schema
(optional) interactionData (object): Additional event data. This data must validate against the specified schema. For example, see the interaction data fields supported by the base schema for apps.
(optional) schemaId (string): Name of the schema to validate the event against. Defaults to the base schema for apps