API Reference

ActionsPerVisit

Piwik\Plugins\CoreHome\Columns\Metrics\

ActionsPerVisit

The average number of actions per visit.

nb_actions / nb_visits

nb_actions & nb_visits are calculated during archiving.

Methods

The class defines the following methods:

getName()

Returns the column name of this metric, eg, "nb_visits" or "avg_time_on_site".

This string is what appears in API output.

Signature

  • It returns a string value.

getTranslatedName()

Returns the human readable translated name of this metric, eg, "Visits" or "Avg. time on site".

This string is what appears in the UI.

Signature

  • It returns a string value.

getCategoryId()

Returns the category that this metric belongs to.

Signature

  • It returns a string value.

getDocumentation()

Returns a string describing what the metric represents. The result will be included in report metadata API output, including processed reports.

Implementing this method is optional.

Signature

  • It returns a string value.

getSemanticType()

Returns this metric's semantic type. This can be used to provide the semantic type for processed metrics.

A metric's semantic type is metadata used primarily in integrations with Matomo and third party services/applications. It provides information that can be used to determine how to display or use the information.

It is recommended for your plugin to provide this information so users of third party services that connect with Matomo can make full use of the data your plugin tracks.

See Dimension for the list of available semantic types.

Signature

  • Returns: string|null —

format()

Returns a formatted metric value. This value is what appears in API output. From within Matomo (formerly Piwik), (core & plugins) the computed value is used. Only when outputting to the API does a metric get formatted.

By default, just returns the value.

Signature

  • It accepts the following parameter(s):

    • $value (mixed) — The metric value.
    • $formatter (Formatter) — The formatter to use when formatting a value.

  • Returns: mixed — $value

beforeFormat()

Executed before formatting all metrics for a report. Implementers can return false to skip formatting this metric and can use this method to access information needed for formatting (for example, the site ID).

Signature

  • It accepts the following parameter(s):

  • Returns: bool — Return true to format the metric for the table, false to skip formatting.

getMetric()

Helper method that will access a metric in a Row or array either by its name or by its special numerical index value.

Signature

  • It accepts the following parameter(s):

    • $row (Row|array) —

    • $columnName (string) —

    • $mappingNameToId (int[]|null) — A custom mapping of metric names to special index values. By default Metrics::getMappingFromNameToId() is used.

  • Returns: mixed — The metric value or false if none exists.

getMetricValues()

Helper method that will determine the actual column name for a metric in a DataTable and return every column value for this name.

Signature

  • It accepts the following parameter(s):

    • $table (DataTable) —

    • $columnName (string) —

    • $mappingNameToId (int[]|null) — A custom mapping of metric names to special index values. By default Metrics::getMappingFromNameToId() is used.

  • It returns a array value.

getActualMetricColumn()

Helper method that determines the actual column for a metric in a DataTable.

Signature

  • It accepts the following parameter(s):

    • $table (DataTable) —

    • $columnName (string) —

    • $mappingNameToId (int[]|null) — A custom mapping of metric names to special index values. By default Metrics::getMappingFromNameToId() is used.

  • It returns a string value.

compute()

Computes the metric using the values in a Row.

The computed value should be numerical and not formatted in any way. For example, for a percent value, 0.14 should be returned instead of "14%".

Signature

  • It accepts the following parameter(s):

    • $row (Row) —

  • It returns a mixed value.

getDependentMetrics()

Returns the array of metrics that are necessary for computing this metric. The elements of the array are metric names.

Signature

  • It returns a string[] value.

getTemporaryMetrics()

Returns the array of metrics that are necessary for computing this metric, but should not be displayed to the user unless explicitly requested. These metrics are intermediate metrics that are not really valuable to the user. On a request, if showColumns or hideColumns is not used, they will be removed automatically.

Signature

  • It returns a string[] value.

beforeCompute()

Executed before computing all processed metrics for a report. Implementers can return false to skip computing this metric.

Signature

  • It accepts the following parameter(s):

  • Returns: bool — Return true to compute the metric for the table, false to skip computing this metric.