# Custom Metrics & Dimensions

WARNING

This page is intended as a guide to grast the basic concepts.

Please contact your sales rep, customer engineer manager, or customer success manager to get assistance on how to collect your custom metrics and custom dimensions.

The Unified Plugin allows the collection of Out-of-the-box Metrics and also the collection of custom metrics and dimensions.

Here, you can find instructions and guidance on how to create your own custom metrics and dimensions.

# Metrics

Metrics are quantitative measures or numerical data that can be used to analyze trends and performance. Examples of metrics include number of plays, duration, and bitrate. Metrics are usually represented as integers or floats and can be used to create charts, graphs, and reports. Metrics can also be used in mathematical operations to create new metrics or to analyze relationships between different metrics.

Custom metrics are metrics that are created by the user and are not collected out of the box. They can be created to store additional data, allowing for more customized reporting and analysis. Custom metrics can also be used to perform calculations or operations on existing metrics, creating new metrics that provide more insight into the data being analyzed.

When working with metrics, it is important to understand the context in which each metric is being used. Metrics should be carefully selected and used in conjunction with other metrics and dimensions to provide a comprehensive understanding of the data being analyzed.

# Special Details

When creating custom metrics, it is essential to register both the metric type and the aggregation type to ensure that metric data is saved correctly.

There are several aggregation types available for custom metrics, including MAX, MIN, INSTANT, ACCUMULATED, AVERAGE, SUM, and FIRSTVALUE. Each type operates differently when aggregating data, so it is important to choose the most appropriate type for each metric.

Custom metrics are sent through the /ping and /stop events, and the aggregation type specified during registration is used to process the data. This ensures that the metric data is accurately recorded and can be analyzed as needed.

In summary, custom metrics require careful consideration of both the metric type and the aggregation type. By registering the appropriate types and using the correct endpoints for data ingestion, developers can ensure that their custom metrics accurately capture the desired data and provide valuable insights.

# Limitations

A maximum of 20 custom metrics can be created per account code:

10 integer
10 float

# Implementation

Custom metrics can be sent using the Analytics options object. It is possible to change the value over time, and when doing so the NQS will then aggregate all the data you sent based on the operation you specified. To register a new custom metric called myCustomMetric we should do as follows:

// Example for the js (web) plugin
unifiedPlugin.setAnalyticsOptions({
    'content.metrics': {
        'myCustomMetric': {
            'value': 10,
            'operation': 'MAX'
        }
    }
});

1
2
3
4
5
6
7
8
9

ATTENTION

It is crucial to register metrics with the backend team before sending data to the endpoints. Failure to do so may result in the creation of unclassified metrics in the database, rendering it difficult to differentiate between data types such as int or float. Hence, registering the metric before sending the data is essential.

Without specifying the metric type, the data will not be saved until the registration process is completed.

# Dimensions

Dimensions are attributes or characteristics of data that can be used to group or filter data. Examples of dimensions include title, date, geography, user type, and device type. Dimensions are usually represented as strings and can be used to group data for analysis or to filter data to create reports. Custom dimensions are dimensions that are created by the user and are not defined in the panel by Codavel. Custom dimensions can be created to store additional data not collected out of the box, allowing for more customized reporting and analysis.

When using dimensions, it is important to understand that they cannot be used for mathematical operations or calculations. They are used primarily for grouping, filtering, and organizing data.

# Limitations

Maximum custom dimensions: 20 dimensions per account code

# Implementation

To set a custom dimension perform the following code:

// Example for the js (web) plugin
unifiedPlugin.setAnalyticsOptions({
    'content.customDimension.myCustomDimension': value // Value must be string
});

1
2
3
4

If you want more than one, you could do the following:

// Example for the js (web) plugin
unifiedPlugin.setAnalyticsOptions({
    'content.customDimensions': {
        'myCustomDimension1': value,
        'myCustomDimension2': value2,
        ...
    }
});

1
2
3
4
5
6
7
8

Notice that both options can be used at the same time.

INFO

When sending a new custom dimensions for the first time, it is important to be aware that there might be a delay before the data is saved. This delay occurs because the backend must register and create the new dimension before data can be stored.

← Out-of-the-box