Using AppAnalytics in FireMonkey

Go Up to FireMonkey Application Design

RAD Studio integrates AppAnalytics in FireMonkey for all Supported Target Platforms: Win32, Win64, macOS, iOS, and Android, in Delphi and C++Builder applications.

AppAnalytics can help you to understand how the customers use your application. AppAnalytics provides useful information such as the OS version, crashed sessions... and the possibilty of tracking your own custom events which is a powerful tool for the developer.

How to Start Using AppAnalytics in FireMonkey

You need to drop a TAppAnalytics component into your application. Then, in the Object Inspector, add the ApplicationID.

Note: You need to get an AppAnalytics account and an Application ID to be able to use AppAnalytics in your application.

After the AppAnalytics is active, the usage data is available in a few minutes in the AppAnalytics web interface.

Enabling/Disabling Data Collection with AppAnalytics

The FireMonkey implementation of AppAnalytics uses the TAppAnalytics.Enabled property to activate or deactivate the tracking of usage data.

After enabling AppAnalytics, a Privacy Notice appears and asks the user for permission. The tracking of usage data only happens if the user accepts this dialog box. Otherwise, tracking remains inactive.

Note: The image shows the default text of the Privacy Notice. However, you can change this text by modifying the TAppAnalytics.PrivacyMessage property.

When the user gives consent, AllowTracking is set to True, and AppAnalytics collects and sends usage data unless the user disables the tracking.

However, in FireMonkey, the AppAnalytics component does not register the user permission automatically. For this reason, you should manage registration using the SaveState of the form or some other mechanism so that the user permission can persist in future application sessions.

Warning: Neither you nor any of your users should send any personal, private, or identifiable information over this connection. To do so is a violation of the privacy policy.

For more information about how the TAppAnalytics component enforces privacy in FireMonkey, see How to Obtain User Consent for AppAnalytics in FireMonkey.

Configuring Tracking Options for AppAnalytics in FireMonkey

You can decide the data that AppAnalytics automatically collects by selecting any combination of the parameters in the TAppAnalytics.Options property.

You can track the following:

• When the user enables or disables the tracking of usage data (AppStart/AppExit).
• When a window or form is activated (WindowActivated).
• When the application raises an exception (Exception).
• When a visual control receives focus (ControlFocused), which is useful to track the usage of the components of the application.

Additionally, you can define custom events and the mechanism to record events and data about them (Custom).

Other Configuration Options

You can define the maximum number of events that AppAnalytics collects before sending them to the server for analysis using CacheSize.

You can also decide the interval, at which AppAnalytics automatically sends the data it has collected to the server for analysis. This interval is set in miliseconds using the UpdateInterval property.

Both properties are 0 by default.

Warning: We recommend to always set values for the CacheSize and the UpdateInterval properties different from the default values.

Sending Data to the Server

The following list describes the different scenarios, on which the data is sent to the AppAnalytics web interface:

If the TAppAnalytics.Enabled is set to True and the user clicks Yes on the Privacy Notice window:

1. When the CacheSize reaches the defined entries regardless the UpdateInterval value.
2. Every time period defined on the UpdateInterval regardless the CacheSize value.
3. When the TAppAnalytics.Enabled property changes from True to False even if the application is open.
4. When the application closes with a gracefully shutdown.

Custom Event Tracking

AppAnalytics allows the developer to create custom events to find more about how the users use the application.

To record a custom event, follow these steps:

1. Create a TCustomEventContext object to store the event data you want to record. The TCustomEventContext object takes 4 parameters, 3 strings and a Double. The parameters are Category, Action, Text and Value.
   • Use Category to categorize or group the events.
   • Use Action to differentiate actions under the same category.
   • Use Text to create a label for a specific action and value.
   • Use Value to get a value when the event takes place.

Note: None of the strings can be empty.

1. Record the event by passing the TCustomEventContext object to the TAnalyticsManager.RecordActivity method.

Once the data is sent to the server, you can see the information on the Custom Events tab of the application. Click Category to expand and see the rest of the information for this event.

See TCustomEventContext for a demonstration.

See Also

• Using AppAnalytics in VCL
• AppAnalytics web interface
• AppAnalytics product page

Code Samples

• FMX.AppAnalytics Sample for Delphi and C++
• VCL.AppAnalytics Sample
• Tracking Custom Events Code Snippet on FireMokey
• Tracking Custom Events Code Snippet on VCL