Adding custom events

You can use AppMetrica to collect statistics on your custom app events and view the statistics in the Events report in the web interface.

The report has information about the number of users and devices that an event was registered for. Sometimes the data for devices and users doesn't match up. For instance, this can happen if the app is started in the background. In this case, the device shows up in the report, but the user doesn't.

If you are working with events that have a hierarchical structure, they might be shown in different ways in the report, depending on the type of data transmission.

Android

If the event is transmitted using the YandexMetrica.reportEvent(String eventName, String jsonValue) event,

String eventParameters = "{\"name\":\"Alice\", \"age\":\"18\"}";

YandexMetrica.reportEvent("New person", eventParameters);

the report in the web interface shows the following:

iOS

If the event is transmitted using the [YMMYandexMetrica reportEvent:(NSString *)message parameters:(NSDictionary *)params onFailure:(void (^)(NSError *error))onFailure]; method,

NSDictionary *params = @{@"key1": @"value1", @"key2": @"value2"};
[YMMYandexMetrica reportEvent:@"EVENT"
                   parameters:params
                    onFailure:^(NSError *error) {
                        NSLog(@"error: %@", [error localizedDescription]);
                    }];

the report in the web interface shows the following:

The recommendations below for transmitting events to AppMetrica will help you generate reports that are easy to read (this applies to using the Reports API, as well).

  1. Event nesting levels
  2. Interpretation of numeric and string values
  3. Partially matched nested events

Event nesting levels

The AppMetrica web interface displays up to five nesting levels for events. So if an event has six or more levels, only the top five are shown in the report. You can use the Reports API to get up to ten levels.

When sending multi-level events, besides the name of the event itself, you must pass the nested key:value pair (key and value are considered nesting levels).

Interpretation of numeric and string values

The parameters passed to an event can take numeric and string values. When a numeric value reaches the server, it is converted to a string. The parameter's numeric value is stored on the server. It isn't displayed in the web interface, but it can be accessed using the API.

So the values {"count" : 3} and {"count" : "3"} are interpreted the same way. If parameters with different numeric values are passed, these values are not combined in the web interface. Each of them is recorded and calculated separately. However, you can use the Reports API to upload additional fields: the total and average of all numeric values.

Partially matched nested events

If the server receives similar event messages that have different nesting levels, their values are added together on these levels.

Let's look at an example of sending events in JSON. Assume that the server received two event messages.

The first event message has two nesting levels:

String eventParameters = "{\"param1\":\"param2\"}";
YandexMetrica.reportEvent("EVENT", eventParameters);

The second one has three nesting levels:

String eventParameters = "{\"param1\":{\"param2\":\"value\"}}";
YandexMetrica.reportEvent("EVENT", eventParameters);

In this case, the events are counted using the following algorithm:

  1. The event is recorded, along with two of its sublevels. This adds 1 to each of the counters.
  2. We add 1 to the root level (the event itself) and its two sublevels, but leave the third level unchanged.

In the web interface, these events are displayed as a tree view: