Amplitude Plugin

Overview

The Amplitude plugin provides functions for getting insights into your app's usage. This plugin can be used on all supported Felgo platforms. It uses the native Amplitude frameworks on Android and iOS and the JavaScript library on all other platforms.

The Amplitude plugin implements the following features:

• Sessions: Allows common tracking of your application usage (new users, active users and their time spent in your game, user retention, ...).
• Events: Allows tracking of specific user events. E.g. if a user has purchased an item or reached a certain level within a game.
• Audience: Allows specifying user data such as sex and age, and provides information about the geography of your players.

Use Cases

Sessions

Session data is gathered automatically by just inserting the Amplitude plugin into your app and contains information how often users use your app and how long they use it, or how often they return (retention).

Events

In addition to session data, you can define custom Events to track the actions your users make in your app. This is useful for tracking how users actually use your app, to optimize conversion and to segment your users depending on their behavior in the app.

Audience

Demographics and technical details about your Audience are also analyzed automatically. This includes information about the mobile phone and OS version used, and from which countries your users come from. Other audience information like user age and gender can additionally be set within the plugins, which allows an even deeper analysis of your user base.

Amplitude Examples

Plugin Demo App

To try the plugin or see an integration example have a look at the Felgo Plugin Demo app.

Please also have a look at our plugin example project on GitHub: https://github.com/FelgoSDK/PluginDemo.

Example Usage

The Amplitude item can be used like any other QML item. Here is a simple example of how to integrate the plugin in your existing app and track an event named "App Started" after the plugin gets loaded:

 import Felgo

 Amplitude {
   id: amplitude

   // From Amplitude Settings
   apiKey: "<amplitude-api-key>"

   onPluginLoaded: {
     amplitude.logEvent("App started");
   }
 }

Advanced Usage

Amplitude supports some advanced features:

• You can create statistics about your app's earned revenue. Use the function Amplitude::logRevenue() for this. This is useful to analyze the performance of your in-app purchases. Amplitude will show detailed revenue statistics, for example a graph like this:

  

• You can merge events from different devices based on a user ID. This is useful if your app or game uses a login system and you want to track events from the same logged in user on multiple devices. You can achieve such behavior by assigning the same value to Amplitude::userId from each device.

  Note: If you don't need event merging per user ID, this property does not need to be assigned.

• You can set custom device IDs. Amplitude generates a unique UUID for each device automatically. If your app generates device IDs by itself, you can override them using using Amplitude::setDeviceId(). You can also configure Amplitude to use the default advertising identifier instead by setting Amplitude::useAdvertisingIdForDeviceId to true.

  The Amplitude dashboard will group events coming from the same userId, or from the same deviceId if no userId is set, like you can see in this image:

  

• You can set custom user properties. Per default, Amplitude tracks user properties like language, country, device information and more. If your app gathers additional information about your users, like for example age or gender, you can set them using Amplitude::userProperties.

  The Amplitude dashboard will show your custom user properties in addition to the ones it gathers on its own:

  

Example code using all these features:

 import Felgo

 Amplitude {
   id: amplitude

   // From Amplitude Settings
   apiKey: "<amplitude-api-key>"

   deviceId: generateDeviceId()
   userId: generateUniqueId("Gregor")
   userProperties: ({
     age: 17,
     weight: 110.3,
     name: "Gregor",
     achievements: [1, 2, 4, 8]
   })

   onPluginLoaded: {
     amplitude.logEvent("App started");
   }

   function onUserPurchasedSomething() {
     amplitude.logRevenue({
                            productId: "p17",
                            quantity: 3,
                            price: 10, //earned revenue = 3 * 10 = 30
                            revenueType: "income",
                            eventProperties: {
                             extraProp1: 178,
                             extraProp2: "any text"
                            }
                          });
   }
 }

Available QML Items

Adding and Activating Plugins

How to Add a Felgo Plugin to your App or Game

When you create a new project, you can choose to add example plugin integrations as well. Open Qt Creator and choose “File / New File or Project”, then choose Single-Page Application in the Felgo Apps section or any other wizard. For Felgo Games, you can also find an own Game with Plugins project template as an own wizard.

Then select the platforms you want to run your application on. The plugins are available for both iOS & Android. There is a fallback functionality in place on Desktop platforms so your project still works when you call methods of the plugins. This allows you to do the main development on your PC, and for testing the plugin functionality you can run the project on iOS and Android.

After the Kit Selection, you can choose which of the plugins you’d like to add to your project:

Then complete the wizard, your project is now set up with all the correct plugin dependencies for Android & iOS automatically. This includes:

• Setting up the .gradle file for Android.
• Setting up the .plist file for iOS.
• Setting up the CMakeLists.txt file to include the plugin libraries for iOS.

If you have an existing Felgo application, follow these steps to include a plugin to your app or game:

In Qt Creator, select “File / New File or Project” and choose either Felgo Games or Felgo Apps from Files and Classes. Then select Felgo Plugin and press Choose.

You can now select the plugin you want to add:

The plugin item, which contains the chosen plugin and a short usage example, is now added to your project. To use the item in your project, simply perform these steps:

• Include the created item (use the name you entered in the template before) in your main.qml file.
• Modify the CMakeLists.txt file & .plist file for iOS usage. See the iOS integration guide of the chosen plugin for more information.
• Modify the the .gradle file for Android usage. See the Android integration guide of the chosen plugin for more information.

Activating Plugins with a License Key

You can test all plugins as soon as the required integration steps and plugin configuration are completed.

However, the plugins are only available as Trial Versions if they are not activated with a valid license. When you are using unlicensed plugins, a dialog is shown and a watermark overlays your application to notify you about the testing state of the plugin.

All monetization plugins are free to use in all licenses, other plugins are only fully usable if you have purchased the Startup or Business license. To activate plugins and enable their full functionality it is required to create a license key. You can create such a key for your application using the license creation page.

This is how it works:

• Choose the plugins you want to include in your license key:

  

• Click on “Generate License Key” and set the app identifier & version code of your application. You can see that the AdMob plugin was enabled in this license key:

  

• Copy the generated licenseKey to your GameWindow or App component.

  

• You can now fully use the selected plugins!

Integration

To use the Amplitude plugin you need to create an Amplitude account and add the platform-specific native libraries to your project, described here:

Amplitude Account

Set up an Amplitude user account at https://amplitude.com/signup or login to your existing account. First you need to create an organization for your account. Then, open Amplitude settings and add a new application. You can either use the same apiKey for all platforms or create an apiKey for each platform. We suggest to use the same key, because then you can easier see possible differences on these platforms regarding app downloads and user behavior.

Project Configuration

Add the following lines of code to your CMakeLists.txt file:

 set(FELGO_PLUGINS
    amplitude
 )

iOS Integration Steps

1. Download our PluginDemo from https://github.com/FelgoSDK/PluginDemo/archive/master.zip and unzip it.
2. Copy Amplitude.framework from the ios subfolder to a sub-folder called ios within your project directory.
3. If you plan to use the advertising identifier (IDFA) as unique ID, you need to request user authorization to access the IDFA for tracking the user or the device. The Amplitude plugin already includes the logic to present an app-tracking authorization request to the user. To use it, add the following lines to your CMakeLists.txt file.

    if(CMAKE_SYSTEM_NAME STREQUAL "iOS")
      set_property(TARGET TargetApp APPEND PROPERTY INTERFACE_LINK_LIBRARIES
        "-framework AdSupport"
      )
    endif()

   Note: The plugin does not include any AdSupport logic to get the actual IDFA then, it just includes the logic to ask for permission to use it. You need to set the IDFA in QML with the help of the Amplitude::adSupportBlock.

Android Integration Steps

1. Open your build.gradle file and add the following lines to the dependencies block:

    dependencies {
      implementation 'com.felgo.plugins:plugin-amplitude:4.+'
    }

   Note: If you did not create your project from any of our latest wizards, make sure that your project uses the Gradle Build System like described here.

Other Platforms

No additional integration steps are required.

Used Amplitude SDK Versions