Jump to content

Metrics Platform/Swift API

From Wikitech

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

The resulting event:

  • by default, includes action: click
  • includes optional interaction data
  • 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. To submit an interaction event, use submitInteraction.

The resulting event:

  • includes the specified value of action
  • includes optional interaction data provided in interactionData
  • is validated against the specified schema
  • is published to the specified event stream

Implementation

The Swift MPC library is contained in the Event Platform group within the WMF Framework module of the Wikipedia app for iOS. The main client functionality is implemented in EventPlatformClient , along with the StorageManager and SamplingController support classes defined in separate files. Additional files in the group contain Core Data model definitions for event storage.

Stream configurations are fetched from the MediaWiki API via Meta-Wiki on app startup. If the stream configuration request fails, it is retried up to 10 times, with an increasing delay period between retries. Stream configurations are not held in persistent storage for subsequent launches.

Before stream configurations are fetched, any events received by the client are stored unconditionally in an InputBuffer with a maximum size of 128 events. If the input buffer reaches its maximum size, the oldest events are removed as needed to make room for new events. After stream configurations are loaded, events in the InputBuffer are evaluated and conditionally moved to persistent storage in Core Data, where they are held for eventual submission to the Event Platform intake service. Subsequently, the InputBuffer is no longer used, and all events received are evaluated and conditionally held in Core Data for submission.

Every 30 seconds, stale entries are pruned from the event storage table, and an attempt is made to submit all remaining entries for which submission is pending. A stale entry is defined as one that has either been successfully submitted or has existed in the storage table for more than 30 days.

The database storage model is a deviation from the Event Platform Client specification and was carried over from the previous analytics client implementation at the iOS app team's request. There is no plan to update other clients to match this behavior.

Reference

EventPlatformClient.submit (Swift)

Evaluates the stream and submitted data for submission to the Event Platform intake service according to any sampling and filtering rules specified in the stream configuration. If the event passes all sampling and filtering rules, it is supplemented with additional metadata and enqueued for submission to the event platform intake service.

Use submitInteraction and submitClick when creating new instrumentation.

Parameters:

  • stream (Stream): The destination stream name. Stream is an enum defined in the EventPlatformClient class that contains the expected destination stream names as values.
  • event (E: EventInterface): The event data. EventInterface is a protocol (interface) requiring that the event data contain a schema field and implement Codable.
  • domain (String?): An optional domain string, intended to be used where the wiki domain for the current app language does not apply to the event being submitted.

Types:

  • Stream: Enum defined in EventPlatformClient that contains allowed destination stream names as values
  • EventInterface
  • EventInterface: Protocol requiring that the event data has a schema property and implements Codable