How to Add V-Play to a Qt App

How to Add V-Play to your Qt Mobile App

By GT

If you have an existing Qt Mobile App, you can extend your Qt application with V-Play components to improve your mobile app experience. You can mix all of the V-Play 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 V-Play 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 V-Play like this:

import QtQuick 2.0
import QtQuick.Controls 2.0
import VPlayPlugins 2.0

ApplicationWindow {

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

 

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

How does V-Play Improve Qt?

The V-Play SDK for cross-platform apps and games comes with many components to make mobile development with Qt easier. V-Play 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

 

V-Play Apps Component Showcase iOS V-Play Apps Component Showcase Android

 

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

It is possible to use all V-Play 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 V-Play 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 V-Play Components can be freely mixed with other QML Items in your mobile app. To make the learning curve easier, V-Play 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 V-Play projects from scratch – you can even use V-Play 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 V-Play in your Qt application:

 

Add V-Play to your existing Qt Installation

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

If you still would like to add V-Play 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 V-Play installation repository with OK and proceed with the Add or remove components option by pressing the Continue button.

qt_install_vplay_1

5. V-Play 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 V-Play.
qt_install_vplay_4
Note: Each V-Play version is compatible with a certain Qt version. For example, the current version 2.13.1 uses Qt 5.9.0. If you are using an older or newer version of Qt at the moment (e.g. Qt 5.8.0 or Qt 5.9.1), also select Qt 5.9.0 in this step. See the V-Play Update Guide for the currently used Qt version of V-Play.

Alternatively, you can also download the V-Play installer which comes with the supported Qt version automatically. You can install V-Play 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 V-Play Account on the new welcome page, which was added by installing V-Play.

qt_install_vplay_6

8. If you do not have a V-Play Account yet, you can create a new account on the V-Play 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 V-Play 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 V-Play SDK and logged into your V-Play account with Qt Creator, you can start using V-Play in your projects.

Integrate V-Play in your Qt Quick Project

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

1. Modify your .pro file configuration to link the V-Play SDK to your project

CONFIG += v-play

2. Open the main.cpp of your project and initialize V-Play

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

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

    QQmlApplicationEngine engine;
    vplay.initialize(&engine); // 3 - initialize V-Play

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

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

import VPlay 2.0

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

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

import VPlay 2.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": "V-Play App",
    "identifier": "net.vplay.demoapp",
    "orientation": "auto",
    "versioncode": 1,
    "versionname": "1",
    "stage": "test"
}

5. When activating V-Play 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 V-Play in your QML application.

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

Use V-Play Components in your QML Code

Using V-Play in the QML files of your Qt Quick application is easy. All V-Play types are available as QML components and can be used just like any other Item in QML. Mixing V-Play 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 V-Play import and use the Storage component of V-Play:

import VPlay 2.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 V-Play Game Network service to synchronize the stored data across devices of the same user:

import VPlay 2.0

VPlayGameNetwork {
  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 V-Play 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 V-Play.

Access Native Device Features in your Qt App

Another big advantage of V-Play 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 VPlayApps 1.0

App {
AppButton {
  text: "Share!"
  onClicked: nativeUtils.share("V-Play is awesome!", "https://v-play.net")
}
}

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 V-Play 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

V-Play 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 V-Play 2.11.0 it is even possible to fully use V-Play including all monetization plugins with the free Personal Plan of V-Play. 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 VPlayPlugins 1.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 V-Play 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 V-Play 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 V-Play. However, without having a valid V-Play 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 V-Play 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 V-Play in your Qt applications, don’t hesitate to contact us at support@v-play.net 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
V-Play Update 2.12.1: Qt Quick Designer Improvements

How to Make Cross-Platform Mobile Apps with Qt – V-Play 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