How to Add V-Play to a Qt App

How to Add Felgo to your Qt Mobile App

By GT

If you have an existing Qt Mobile App, you can extend your Qt application with Felgo components to improve your mobile app experience. You can mix all of the Felgo and Qt components and have them combined in your project. And the best thing is, you do not need to rewrite your existing Qt application for this! Instead, you can mix the Felgo and Qt components freely in your mobile app. So if you need for example push notifications in your Qt app which uses Qt Quick Controls 2, you can use your existing code and simply add the Google Cloud Messaging (Firebase) push notification plugin by Felgo like this:

import QtQuick 2.0
import QtQuick.Controls 2.0
import Felgo 3.0

ApplicationWindow {

  GoogleCloudMessaging {
    onNotificationReceived: {
      console.debug("Received push notification: ", JSON.stringify(data))
    }
  }
}

 

This blog post is about the exact steps how you can add Felgo to your Qt Mobile App. Let’s get started.

How does Felgo Improve Qt?

The Felgo SDK for cross-platform apps and games comes with many components to make mobile development with Qt easier. Felgo extends Qt for mobile app development and offers for example:

  • Native look and feel for iOS and Android
  • Monetization with Ads and In-App Purchases
  • Analytics for User Behavior and Crash Reports
  • Push Notifications – triggered locally or by a server
  • Social Engagement with native sharing and Facebook integration
  • Gamification with Highscores, Achievements, Friend System and a Chat
  • Web Backend with cross-platform cloud data storage and syncing between multiple devices
  • Responsive Design for screen and device independence
  • Access to Native Device Features like native dialogs, the camera/image picker, phone contacts or content sharing

 

Felgo Apps Component Showcase iOS Felgo Apps Component Showcase Android

 

Note: To learn more about how Felgo improves Qt for mobile app developers and a comparison between Qt and Felgo, you can also see this page.

It is possible to use all Felgo features in your Qt Quick application, no matter if it is based on Qt Quick Controls 1 or Qt Quick Controls 2. It is even possible to use the Felgo components in your Qt Widget based app – you can contact us here if you’d like to get an example project how to do this.

All Felgo Components can be freely mixed with other QML Items in your mobile app. To make the learning curve easier, Felgo comes with many open-source demo and example projects you can use as a starting point for your own projects.

However, it is not only possible to create Felgo projects from scratch – you can even use Felgo Engine in your existing Qt Quick applications to take advantage of the included features in your Qt app. This article will guide you through all the important steps to successfully use Felgo in your Qt application:

 

Looking for Qt Training, Consulting or Software Development?

Add Felgo to your existing Qt Installation

If you already installed Qt 5 on your system, we still recommend to install Felgo in parallel using our installer to avoid any Qt version compatibility issues. The Felgo and Qt installation will work side-by-side in two different directories.

If you still would like to add Felgo to your existing Qt installation, first navigate to the root SDK folder of your Qt installation and open the executable called Maintenance Tool. Then follow these steps:

1. Choose the Add or remove components option so the Settings button is shown in the bottom left corner.

qt_install_vplay_1

2. Click the Settings button and in the Settings window, click on the Repositories tab.

qt_install_vplay_2

3. Choose the bottom section User defined repositories and click the Add Repository button. Then enter the URL for your development platform in the text box. It is either:

  • https://sdk.v-play.net/2/windows
  • https://sdk.v-play.net/2/macx
  • https://sdk.v-play.net/2/linux

qt_install_vplay_3

4. Next, confirm the Felgo installation repository with OK and proceed with the Add or remove components option by pressing the Continue button.

qt_install_vplay_1

5. Felgo Engine will now show up in addition to the available Qt modules. Make sure that it is checked in the Package Manager and proceed with the MaintenanceTool to install Felgo.
qt_install_vplay_4
Note: Each Felgo version is compatible with a certain Qt version. See the Felgo Update Guide for the currently used Qt version of Felgo.

Alternatively, you can also download the Felgo installer which comes with the supported Qt version automatically. You can install Felgo side-by-side with Qt in a different directory. They will both work independently from each other then.

6. Choose Done when the installation has finished to close the installer.

qt_install_vplay_5

7. You can now open Qt Creator and log-in to your Felgo Account on the new welcome page, which was added by installing Felgo.

qt_install_vplay_6

8. If you do not have a Felgo Account yet, you can create a new account on the Felgo Website. Open the downloads page and choose Download to open the sign-up popup, which will guide you through the registration. As you already added Felgo to your Qt installation, you can skip the actual download after you’ve completed the sign-up.

qt_install_vplay_7

After you’ve successfully installed the Felgo SDK and logged into your Felgo account with Qt Creator, you can start using Felgo in your projects.

Integrate Felgo in your Qt Quick Project

To correctly link and initialize the Felgo components, some additional steps are required for each project that uses Felgo. First, open your Qt Quick Project with Qt Creator. You can then follow these steps to add Felgo:

1. Modify your .pro file configuration to link the Felgo SDK to your project

CONFIG += felgo

2. Open the main.cpp of your project and initialize Felgo

#include <QGuiApplication>
#include <QQmlApplicationEngine>
#include <FelgoApplication> // 1 - include VPApplication

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    FelgoApplication felgo; // 2 - create FelgoApplication instance

    QQmlApplicationEngine engine;
    felgo.initialize(&engine); // 3 - initialize Felgo

    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));
    return app.exec();
}

3. In your main.qml, use Felgo GameWindow or App as your main ApplicationWindow (this is required for license validation and other checks)

import Felgo 3.0

GameWindow {
  licenseKey: ""
  // ...
}

Alternatively, you can also add a GameWindowItem as a child to your main window instead:

import Felgo 3.0

ApplicationWindow {
    // ...
    GameWindowItem {
      licenseKey: ""
    }
}

4. Add a new file qml/config.json to your project resources, and configure your correct application id and version:

{
    "title": "Felgo App",
    "identifier": "net.vplay.demoapp",
    "orientation": "auto",
    "versioncode": 1,
    "versionname": "1",
    "stage": "test"
}

5. When activating Felgo with a valid license key, the identifier and version of the config.json needs to match the actual app id and version of your mobile app. For Android apps, the identifier and version are configured in the AndroidManifest.xml:

<manifest package="net.vplay.demoapp" android:versionCode="1" … >

If your application does not yet have an Android configuration, you can choose the Projects tab in Qt Creator, select the Android Kit, expand the Build Android APK section and choose Create Templates. This will create a default configuration within a new android subfolder of your project, which also includes the manifest.

6. For iOS, you can set the identifier and version in the Info.plist configuration of your app:

   <key>CFBundleIdentifier</key>
   <string>net.vplay.demoapp</string>
   <key>CFBundleVersion</key>
   <string>1</string>

This configuration file is created by qmake when building for iOS. You can add the following qmake entry to your *.pro configuration to keep and use a custom iOS configuration for your project:

ios {
   QMAKE_INFO_PLIST = ios/Info.plist
}

Make sure to have the correct setting for all three configuration files. If everything looks good, you are ready to use Felgo in your QML application.

You can download this example from GitHub as a reference project too:

Use Felgo Components in your QML Code

Using Felgo in the QML files of your Qt Quick application is easy. All Felgo types are available as QML components and can be used just like any other Item in QML. Mixing Felgo types with Qt components like Qt Quick Controls 2 is also possible.

For example, if you like to add add an easy-to-use local storage to your application, simply add the Felgo import and use the Storage component of Felgo:

import Felgo 3.0

Storage {
  id: localStorage
  property int counter

  onCounterChanged: localStorage.setValue("counter", counter)
  Component.onCompleted: counter = localStorage.getValue("counter") || 0
}

This example saves a counter property in a local SQLite database. The code loads the previous counter value at app start and automatically stores the counter every time it is changed in the app.

It is even possible to use the WebStorage item instead, which utilizes the Felgo Game Network service to synchronize the stored data across devices of the same user:

import Felgo 3.0

FelgoGameNetwork {
  id: gameNetwork
  gameId: <your-vplay-gamenetwork-id>
  secret: "<your-vplay-gameetwork-secret>"
}

WebStorage {
  id: localStorage

  property int counter

  onCounterChanged: localStorage.setValue("counter", counter)
  Component.onCompleted: counter = localStorage.getValue("counter") || 0
}

This is all the code required to include a simple cloud-based data storage.

Other Felgo Components offer the same ease-of-use, for an overview of all available types and features, please have a look at the online documentation of Felgo.

Access Native Device Features in your Qt App

Another big advantage of Felgo is the possibility to use native device features like the camera or confirmation and input dialogs – the NativeUtils component is all you need.

This example shares a custom text and url with the native share dialog on Android and iOS:

import Felgo 3.0

App {
AppButton {
  text: "Share!"
  onClicked: nativeUtils.share("Felgo is awesome!", "https://felgo.com")
}
}

Taking a photo with the camera and displaying the shot afterwards is just as simple:

// open camera on button click
AppButton {
  text: "Take Photo"
  onClicked: nativeUtils.displayCameraPicker("Take Photo")
}

// show image after photo was taken
Connections {
  target: nativeUtils
  onCameraPickerFinished: {
    if(accepted) {
      image.source = path
    }
  }
}

AppImage {
  id: image
  anchors.fill: parent
  fillMode: AppImage.PreserveAspectFit
  autoTransform: true
}

When working with dialogs, the Felgo Apps type NativeDialog is also available and offers a more convenient usage to trigger a dialog and handle the response:

AppButton {
   text: "Confirm Dialog"
   onClicked: NativeDialog.confirm("Please Confirm", "Confirm this action?", function(ok) {
     if(ok) {
       // confirmed
     }
     else {
       // not confirmed
     }
   })
 }

Integrate Third-party Services in your Qt Mobile App

Felgo Plugins allow to integrate leading third-party services for ads, analytics, push notifications and more. All native plugins are available to use in your Qt Quick application and offer a convenient way to fast-forward app and game development for iOS and Android.

Since Felgo 2.11.0 it is even possible to fully use Felgo including all monetization plugins with the free Personal Plan of Felgo. Adding services like Google AdMob, Chartboost or Soomla In-App Purchases has never been easier.

plugindemo-admob-android_opt

a. Native Plugin Integration in Qt

With a single import and QML Item, you can for example show an AdMob Banner in your app:

import Felgo 3.0

AdMobBanner {
  adUnitId: "<your-admob-banner-adUnitId>"
  banner: AdMobBanner.Smart
  anchors.bottom: parent.bottom
}

To actually use the plugin with this simple approach on iOS or Android, a few more steps are required. For example, linking the Android Libraries for Google AdMob with your application requires the following gradle dependency:

allprojects {
  repositories {
      maven { url 'https://sdk.v-play.net/maven/' } // add Felgo repository
  }
}

dependencies {
  compile 'net.vplay.plugins:plugin-admob:2.+' // import admob plugin libraries
}

Just have a look at the plugin documentation of your desired plugin and view the integration steps for more information.

To also prepare the above example for iOS, first copy the GoogleMobileAds.framework from the ios subfolder of the Felgo Plugin Demo on GitHub to a sub-folder called ios within your project. Then add this setting to the qmake configuration in your *.pro file:

ios {
  VPLAY_PLUGINS += admob
}

A short extension to the Project-Info.plist configuration of your iOS app completes the iOS integration steps for using AdMob:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    <key>NSAllowsArbitraryLoadsForMedia</key>
    <true/>
    <key>NSAllowsArbitraryLoadsInWebContent</key>
    <true/>
</dict>

b. Plugin Activation

Monetization plugins are usable with the free version of Felgo. However, without having a valid Felgo License Key set, only trial-modes are available for all plugins. To be able to set the GameWindowItem::licenseKey with a valid key, let’s first create a new key for the app.

After signing in to your Felgo account, you can create as many keys as you want in the License Key Creation section of the Developers Dashboard. This is how it works:

1. Choose the plugins you want to include in your license key:
plugin-activation-license-1

2. 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:
plugin-activation-license-2

3. Copy the generated licenseKey to your GameWindowItem, GameWindow, or App component.
plugin-activation-license-3

4. You can now fully use the AdMob plugin on both iOS and Android!

This approach is the same for every plugin and each license key you create allows to activate all the plugins you need. If you encounter any issues when using Felgo in your Qt applications, don’t hesitate to contact us at support@felgo.com or in the support forums.

The full example of this guide also available on GitHub:

 

 

More Posts Like This

 

Release 2.12.1: Visual Editor & Qt Quick Designer Improvements
Felgo Update 2.12.1: Qt Quick Designer Improvements

How to Make Cross-Platform Mobile Apps with Qt – Felgo Apps

How to Make a Qt app

Release 2.11.0: All Monetization Plugins Now Free, Plugin Trial & Firebase Qt Plugin

Release 2_11

WeAreDevelopers Conference App – Open Source & Live Now!

WeAreDevelopers

Voted #1 for:

  • Easiest to learn
  • Most time saving
  • Best support

Develop Cross-Platform Apps and Games 50% Faster!

  • Voted the best supported, most time-saving and easiest to learn cross-platform development tool
  • Based on the Qt framework, with native performance and appearance on all platforms including iOS and Android
  • Offers a variety of plugins to monetize, analyze and engage users
FREE!
create apps
create games
cross platform
native performance
3rd party services
game network
multiplayer
level editor
easiest to learn
biggest time saving
best support