Using AppAnalytics in FireMonkey
Go Up to FireMonkey Application Design
Appmethod integrates AppAnalytics in FireMonkey for all Supported Target Platforms: Win32, Win64, MacOSX, iOS, and Android, in Object Pascal and Appmethod C++ 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
- 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.
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 (
- When a window or form is activated (
- When the application raises an 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 (
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:
- When the CacheSize reaches the defined entries regardless the UpdateInterval value.
- Every time period defined on the UpdateInterval regardless the CacheSize value.
- When the TAppAnalytics.Enabled property changes from
Falseeven if the application is open.
- 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:
- 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.
- 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.