FMX.AppAnalytics Sample

From RAD Studio Code Examples
Jump to: navigation, search

The App Analytics sample allows you to get used to the basic AppAnalytics component features using FireMonkey, and to be able to upload usage data of the application to the Embarcadero AppAnalytics server.

This sample can be run on all supported platforms: Windows, OSX, iOS, and Android. It is implemented in Delphi and C++Builder.

Location

You can find the App Analytics sample project at:

  • Start | Programs | Embarcadero RAD Studio Rio | Samples and navigate to:
    • Object Pascal\Multi-Device Samples\Device Sensors and Services\App Analytics
    • CPP\Multi-Device Samples\Device Sensors and Services\App Analytics
  • Subversion Repository:
    • You can find Delphi and C++ code samples in GitHub Repositories. Search by name into the samples repositories according to your RAD Studio version.

Description

This sample shows the basic TAppAnalytics component features. You can include this component in your applications in order to obtain usage data from the users. The App Analytics sample demonstrates how to enable information tracking and how to manage privacy by obtaining user consent. The sample also allows you to perform some actions that the TAppAnalytics component tracks and sends to the AppAnalytics web server.

Warning: App Analytics sample does not collect or transmit any private or personally identifiable information. It is totally anonymous.

Before running the sample, you should add an ApplicationID; see the steps you need to follow to obtain an application ID. If you have not included the Application ID, you will not be able to enable AppAnalytics. Instead, you will see the following window:

AppanalyticsNoAppID.png

The first time you try to enable AppAnalytics, a window dialog with Yes and No buttons appears. This is to obtain the user consent to start the tracking of information.

  • If you select Yes, this means that you are giving consent and therefore the TAppAnalytics component is enabled.
  • If you select No, this means that you are refusing permission and the component will remain inactive.

PrivacynoticeFMX.png

Once you enable TAppAnalytics the application form will show like this:

AppanalyticsConnected.png

In the CONNECTION panel, you can see that the Status appears as connected, and a UserID number is displayed.

When you accept the privacy message, the application keeps this consent as long as the application is running. This sample uses the OnSaveState event of the FireMonkey form to persist this setting into a temporary file on disk. The next time the application is started, the OnCreate event detects this temporary file and restores this setting. Clicking the Clear Permission button will remove this saved state and require the application to obtain user consent before the TAppAnalytics component can be enabled again.

In the ACTIONS panel, you can perform some actions that the TAppAnalytics component tracks and sends to the Embarcadero AppAnalytics server. For example, you can launch a second form and raise an exception.

Getting Your Application ID

To run the sample you need an Application ID that uniquely identifies your application. The Application ID is provided by the AppAnalycis web interface. To get an Application ID:

  1. Go to AppAnalytics web interface and sign in; you can sign in with your EDN account.
  2. Once you have signed in, you need to create a new application.
  3. Enter the Application Name and click Save. Then, AppAnalycis provides you with an Application ID.
  4. You need to copy the full Application ID, including both curly brackets { and }, as you need to add this ID in the ApplicationID property of the TAppAnalytics component.

You can view the Application ID at any time by signing in the AppAnalytics web interface.

How to Use the Sample

  1. Navigate to the either of the locations given above.
  2. Open the project file:
    • Delphi: FMXAnalytics.dproj
    • C++: FMXAnalytics.cbproj
  3. Select the target platform.
  4. Select the TAppAnalytics component.
  5. In the Object Inspector, add the Application ID you obtained in the previous section, to the ApplicationID property.
  6. Run the application by clicking Run > Run in the IDE or by pressing F9.

Implementation

This sample uses the TAppAnalytics component that collects usage information and sends it to the Embarcadero AppAnalytics server.

Component Configuration

The TAppAnalytics can be configured by setting some parameters. In this sample:

  • The CacheSize property is set to 10. This value represents the maximum number of events that AppAnalytics collects before sending them to the server for analysis.
  • The UpdateInterval property is set to 10000 miliseconds. This value represents the interval at which AppAnalytics automatically sends the data it has collected to the server for analysis.
  • You can also choose the data that AppAnalytics automatically collects by selecting any combination of the parameters in TAppAnalytics.Options. The sample selects the following options:
    • AppStart/AppExit track when the user enables or disables the tracking of usage data.
    • WindowActivated tracks when a window or form is activated.
    • Exception tracks when the application raises an exception.
    • ControlFocused tracks when a visual control receives focus, which is useful to track the usage of the components of the application.

User consent for data tracking

The TAppAnalytics component enforces privacy. That means that it will not be enabled until it receives user consent. This sample uses the TAppAnalytics.PrivacyMessage property to ask the user for permission. If the user gives consent, an activity listener object is instantiated and registered. The AllowTracking is set to True. This property allows you to save the user consent in an application setting file and to retrieve this setting during the startup sequence.

Uses

See Also