Chartboost

The Chartboost item allows monetizing your games by embedding Chartboost ads on Android and iOS. More...

Import Statement: import VPlayPlugins.chartboost 1.1
Inherits:

Item

Properties

Signals

Methods

Detailed Description

The Chartboost plugin allows monetizing your apps & games by embedding ads from the Chartboost ad network or cross-promote other games from you or other developers.

Use Cases

Advertising campaigns can be used to earn revenue by showing ads, while cross-promotions make it simple to tell existing players about a new game.

Beside classic advertising and cross-promotion Chartboost also offers Rewarded videos, which are an ad type that give the player a reward (e.g. premium currency) after watching a mobile app trailer.

Advertising

Chartboost is an ad network specifically designed for games and targeted at gamers. Therefore only ads for games (and not apps in general) are displayed. The available standard ad type in Chartboost are interstitial ads, which can be shown between game sessions or at startup.

With Chartboost interstitial ads you can generate revenue for each click or install your games deliver, depending how the developer on the advertising side bids.

To show an interstitial ad call showInterstitial() from within your code. For quicker load times, we recommend caching data prior to making this call with cacheInterstitial().

Cross-Promotion

Additionally, Chartboost offers the so-called "More Apps" page, on which you can either cross-promote your own games or games of other developers. This allows driving traffic from existing games to new ones.

Chartboost allows a lot of different types of advertising campaigns like cross-promotion or direct deals. For detailed information on Chartboost settings consult the Chartboost documentation.

To show an "More Apps" page call showMoreApps() from within your code. For quicker load times, we recommend caching data prior to making this call with cacheMoreApps().

Named Locations

Named Locations allow you to show ads at different points within your game and fine-tune campaign behavior from the Chartboost dashboard without the need of updating your apps.

You can either define your own custom location names or use one of the predefined which matches your game's location best:

  • Chartboost.DefaultLocation
  • Chartboost.StartupLocation
  • Chartboost.HomeScreenLocation
  • Chartboost.MainMenuLocation
  • Chartboost.GameScreenLocation
  • Chartboost.AchievementsLocation
  • Chartboost.QuestsLocation
  • Chartboost.PauseLocation
  • Chartboost.LevelStartLocation
  • Chartboost.LevelCompleteLocation
  • Chartboost.TurnCompleteLocation
  • Chartboost.IAPStoreLocation
  • Chartboost.GItemStoreLocation
  • Chartboost.GameOverLocation
  • Chartboost.LeaderboardLocation
  • Chartboost.SettingsLocation
  • Chartboost.QuitLocation

If you omit a location parameter the default value Chartboost.DefaultLocation is used.

Note: Although it's possible to define own location identifiers it's recommended to use one of the predefined ones.

It's also recommended to have a maximum of 5-7 named locations per game.

Plugin Integration

In order to use the Chartboost plugin within your existing Qt 5 project you need a valid Chartboost plugin license key from V-Play, which can be purchased here: http://plugins.v-play.net/plugins/chartboost/.

You also need to install the Chartboost plugin to your Qt 5 installation and adapt your project settings, make sure to perform the actions described in our V-Play Plugins Installation guide before continuing with the following steps.

iOS Integration Steps

  1. Download our ChartboostSample from https://github.com/vplayplugins/ChartboostSample/archive/master.zip and unzip it.
  2. Copy Chartboost.framework from the ios sub-folder to a sub-folder called ios within your project directory.
  3. Add the following lines of code to your .pro file:
     ios {
       LIBS += -F$$PWD/ios -framework Chartboost
     }
    

Android Integration Steps

  1. Open your build.gradle file and add the following lines to the dependencies block:
     dependencies {
       // Add Play Services & support library
       compile 'com.google.android.gms:play-services:7.5.0'
     }
    

    Note: Make sure that your project uses the Gradle Build System like described here.

  2. Download the Chartboost Android SDK from https://github.com/vplayplugins/ChartboostSample/raw/master/android/libs/chartboost.jar.
  3. Copy chartboost.jar to a subdirectory called libs within your Android source sub-directory, most probably under the path android/libs/ within your project directory.
  4. Open your AndroidManifest.xml file and make sure that the following permissions are set:
     <uses-permission android:name="android.permission.INTERNET"/>
     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    

    It's also recommended to set the following permissions:

     <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    

Chartboost Account

You finally need to set up a Chartboost user account at https://www.chartboost.com. Then open your Chartboost dashboard (https://dashboard.chartboost.com) and add an app & a campaign for your game. If you're publishing your game for both iOS & Android you should add two apps (and campaigns), as links to other games are platform-specific.

Note: It can take up to an hour until your new campaigns are available on devices.

Chartboost Plugin Versions

Note: You need a new plugin license key for every new major plugin release.

v 1.1.5 (2015-06-15)

Used Chartboost SDK versions

iOS 5.4.0
Android 5.4.1

Note: Other SDK versions higher than the stated ones might also be working but are not actively tested as of now.

Changes

  • If you're using V-Play Game Engine it's now possible to use a global V-Play license key for this plugin.

v 1.1.4 (2014-12-17)

Supported Chartboost SDK versions

iOS 5.0.x
Android 5.0.x

Changes

  • Changed QML import from "VPlay.plugins.chartboost" to "VplayPlugins.chartboost"

v 1.1 (2014-11-05)

Supported Chartboost SDK versions

iOS 5.0.x
Android 5.0.x

Changes

  • Updated Chartboost SDK libraries to 5 and 15
  • Renamed signal handlers to match Chartboost SDK names
  • Added rewarded videos API (Chartboost Video )

v 1.0 (2014-04-28)

Supported Chartboost SDK versions

iOS 4.4.x
Android 4.1.x

Changes

  • Initial release

Example Usage

The Chartboost item can be used like any other QML item. Here is a simple example of how to integrate the plugin in your existing game to display interstitial ads, but not the More Apps page:

 import VPlayPlugins.chartboost 1.1

 Chartboost {
   id: chartboost
   licenseKey: "<your-plugin-license-key>"

   appId:  "<your-app-id-here>"
   appSignature:  "<your-app-signature-here>"

   // Do not use reward videos in this example
   shouldDisplayRewardedVideo: false

   // Call this function to display an interstitial ad at the default location
   function showAdIfAvailable() {
     chartboost.showInterstitial()
   }

   onInterstitialCached: {
     console.debug("InterstitialCached at location:", location)
   }

   onInterstitialFailedToLoad: {
     console.debug("InterstitialFailedToLoad at location:", location, "error:", error)
   }

 }

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

Property Documentation

appId : string

Provide your Chartboost app-id here. If you do not have an app-id yet, please read Chartboost Account. As some features of Chartboost are platform-specific the following example code shows you how to use different app ids for Android and iOS:

 Chartboost {
   appId: Qt.platform.os === "ios" ? "<ios-appp-id>" : "<android-app-id>"
 }

appSignature : string

Provide your Chartboost app-signature here. If you do not have an app-signature yet, please read Chartboost Account. As some features of Chartboost are platform-specific the following example code shows you how to use different app ids for Android and iOS:

 Chartboost {
   appSignature: Qt.platform.os === "ios" ? "<ios-app-id>" : "<android-app-id>"
 }

shouldDisplayInterstitial : bool

Set this property to control whether interstitials should be displayed within your game or not. Settings this property to false globally disables all interstitials regardless of the given location.

The default value is true.


shouldDisplayLoadingViewForMoreApps : bool

Set this property to false to prevent a loading screen during the More Apps overlay is loaded from the server.

The default value is true.


shouldDisplayMoreApps : bool

Set this property to control whether the More Apps page should be displayed within your game or not. Settings this property to false globally disables all More Apps overlays regardless of the given location.

The default value is true.


shouldDisplayRewardedVideo : bool

Set this property to control whether a reward video should be displayed within your game or not. Settings this property to false globally disables all reward video overlays regardless of the given location.

The default value is true.


shouldPrefetchVideoContent : bool

By default Chartboost prefetches video content of reward videos for a continuous playback of a video. If you want to disable this behavior you can set this property to false.

The default value is true.


shouldRequestInterstitial : bool

Set this property to control whether interstitials should be loaded from the server or not. Settings this property to false globally disables all interstitials regardless of the given location.

As an example you can set this property to false to disable all ads as soon as your user purchased a "no ads" in-app purchase.

The default value is true.


shouldRequestInterstitialsInFirstSession : bool

It's good practice to show interstitials only after the user has played your game for the first time. This property therefore defaults to true.

You can override this behavior when setting the property to false.


shouldRequestMoreApps : bool

Set this property to control whether a More Apps page should be loaded from the server or not. Settings this property to false globally disables all More Apps overlays regardless of the given location.

As an example you can set this property to false to disable all ads as soon as your user purchased a "no ads" in-app purchase.

The default value is true.


Signal Documentation

interstitialCached(string location)

Emitted after an interstitial has been loaded from the server and cached locally for the given location.

See also showInterstitial().


interstitialClicked(string location)

Emitted after an interstitial has been clicked for the given location. "Clicked" is defined as clicking within the interstitial which usually brings your app to the background and open the app store.

See also interstitialDismissed and interstitialClosed.


interstitialClosed(string location)

Emitted after an interstitial has been closed for the given location. "Closed" is defined as clicking the close button within the interstitial.

See also interstitialDismissed and interstitialClicked.


interstitialDismissed(string location)

Emitted after an interstitial has been dismissed for the given location. "Dismissal" is defined as any action that removed the interstitial like a click or close.

See also interstitialClosed and interstitialClicked.


interstitialDisplayed(string location)

Emitted after an interstitial has been displayed on the screen for the given location.

See also interstitialDismissed, interstitialClicked, and interstitialClosed.


interstitialFailedToLoad(string location, string error)

Emitted after an interstitial has attempted to load from the server but failed for the given location.

You can use the error parameter to retrieve a text representation of the occurred error.


moreAppsCached(string location)

Emitted after a More Apps overlay has been loaded from the server and cached locally for the given location.

See also showMoreApps().


moreAppsClicked(string location)

Emitted after a More Apps overlay has been clicked for the given location. "Clicked" is defined as clicking within the More Apps overlay which usually brings your app to the background and open the app store.

See also moreAppsDismissed and moreAppsClosed.


moreAppsClosed(string location)

Emitted after a More Apps overlay has been closed for the given location. "Closed" is defined as clicking the close button within the More Apps overlay.

See also moreAppsDismissed and moreAppsClicked.


moreAppsDismissed(string location)

Emitted after a More Apps overlay has been dismissed for the given location. "Dismissal" is defined as any action that removed the More Apps overlay like a click or close.

See also moreAppsClosed and moreAppsClicked.


moreAppsDisplayed(string location)

Emitted after a More Apps overlay has been displayed on the screen for the given location.

See also moreAppsDismissed, moreAppsClicked, and moreAppsClosed.


moreAppsFailedToLoad(string location, string error)

Emitted after a More Apps overlay has attempted to load from the server but failed for the given location.

You can use the error parameter to retrieve a text representation of the occurred error.


recordClickFailed(string uri, string error)

Emitted after a click got registered, but the user is not forwarded to the app store.

See also interstitialClicked, moreAppsClicked, and rewardedVideoClicked.


rewardedVideoCached(string location)

Emitted after a reward video has been loaded from the server and cached locally for the given location.

See also showRewardedVideo().


rewardedVideoClicked(string location)

Emitted after a reward video has been clicked for the given location. "Clicked" is defined as clicking within the reward video which usually brings your app to the background and open the app store.

See also rewardedVideoDismissed and rewardedVideoClosed.


rewardedVideoClosed(string location)

Emitted after a reward video has been closed for the given location. "Closed" is defined as clicking the close button within the interstitial.

See also rewardedVideoDismissed and rewardedVideoClicked.


rewardedVideoCompleted(string location, int reward)

Emitted after a reward video has been viewed completely and user is eligible for reward for the given location.

See also rewardedVideoDisplayed and rewardedVideoClicked.


rewardedVideoDismissed(string location)

Emitted after a reward video has been dismissed for the given location. "Dismissal" is defined as any action that removed the interstitial like a click or close.

See also rewardedVideoClosed and rewardedVideoClicked.


rewardedVideoDisplayed(string location)

Emitted after a reward video has been displayed on the screen for the given location.

See also rewardedVideoDismissed, rewardedVideoClicked, and rewardedVideoClosed.


rewardedVideoDisplaying(string location)

Emitted immediately before a video has been displayed on the screen for the given location. You can use the signal to do things like muting sound effects or sounds.

See also rewardedVideoDisplayed.


rewardedVideoFailedToLoad(string location, string error)

Emitted after a reward video has attempted to load from the server but failed for the given location.

You can use the error parameter to retrieve a text representation of the occurred error.


Method Documentation

void cacheInterstitial(string location)

Use this method to prefetch and cache an interstitial for the given location. When finished the interstitialCached signal is emitted.

See also hasInterstitial(), showInterstitial(), interstitialCached, and interstitialFailedToLoad.


void cacheInterstitial(enumeration location)

Use this method to prefetch and cache an interstitial for the given location. When finished the interstitialCached signal is emitted.

See also hasInterstitial(), showInterstitial(), interstitialCached, and interstitialFailedToLoad.


void cacheMoreApps(string location)

Use this method to prefetch and cache a More Apps overlay for the given location. When finished the moreAppsCached signal is emitted.

See also hasMoreApps(), showMoreApps(), moreAppsCached, and moreAppsFailedToLoad.


void cacheMoreApps(enumeration location)

Use this method to prefetch and cache a More Apps overlay for the given location. When finished the moreAppsCached signal is emitted.

See also hasMoreApps(), showMoreApps(), moreAppsCached, and moreAppsFailedToLoad.


void cacheRewardedVideo(string location)

Use this method to prefetch and cache a reward video for the given location. When finished the rewardedVideoCached signal is emitted.

See also hasRewardedVideo(), showRewardedVideo(), rewardedVideoCached, and rewardedVideoFailedToLoad.


void cacheRewardedVideo(enumeration location)

Use this method to prefetch and cache a reward video for the given location. When finished the rewardedVideoCached signal is emitted.

See also hasRewardedVideo(), showRewardedVideo(), rewardedVideoCached, and rewardedVideoFailedToLoad.


void hasInterstitial(string location)

Use this method to determine if there is a locally cached interstitial for the given location. If this methods returns true no further server calls are necessary to display the interstitial.

See also cacheInterstitial() and showInterstitial().


void hasInterstitial(enumeration location)

Use this method to determine if there is a locally cached interstitial for the given location. If this methods returns true no further server calls are necessary to display the interstitial.

See also cacheInterstitial() and showInterstitial().


void hasMoreApps(string location)

Use this method to determine if there is a locally cached More Apps overlay for the given location. If this methods returns true no further server calls are necessary to display the More Apps overlay.

See also cacheMoreApps() and showMoreApps().


void hasMoreApps(enumeration location)

Use this method to determine if there is a locally cached More Apps overlay for the given location. If this methods returns true no further server calls are necessary to display the More Apps overlay.

See also cacheMoreApps() and showMoreApps().


void hasRewardedVideo(string location)

Use this method to determine if there is a locally cached interstitial for the given location. If this methods returns true no further server calls are necessary to display the interstitial.

See also cacheRewardedVideo() and showRewardedVideo().


void hasRewardedVideo(enumeration location)

Use this method to determine if there is a locally cached interstitial for the given location. If this methods returns true no further server calls are necessary to display the interstitial.

See also cacheRewardedVideo() and showRewardedVideo().


void showInterstitial(string location)

Use this method to present an interstitial at the given location. If there is no interstitial in the cache, it will start downloading an interstitial and display it right after it has finished loading.

See also hasInterstitial(), cacheInterstitial(), interstitialDisplayed, interstitialDismissed, interstitialClosed, and interstitialClicked.


void showInterstitial(enumeration location)

Use this method to present an interstitial at the given location. If there is no interstitial in the cache, it will start downloading an interstitial and display it right after it has finished loading.

See also hasInterstitial(), cacheInterstitial(), interstitialDisplayed, interstitialDismissed, interstitialClosed, and interstitialClicked.


void showMoreApps(string location)

Use this method to present a More Apps overlay at the given location. If there is no More Apps overlay in the cache, it will start downloading a More Apps overlay and display it right after it has finished loading.

See also hasMoreApps(), cacheMoreApps(), moreAppsDisplayed, moreAppsDismissed, moreAppsClosed, and moreAppsClicked.


void showMoreApps(enumeration location)

Use this method to present a More Apps overlay at the given location. If there is no More Apps overlay in the cache, it will start downloading a More Apps overlay and display it right after it has finished loading.

See also hasMoreApps(), cacheMoreApps(), moreAppsDisplayed, moreAppsDismissed, moreAppsClosed, and moreAppsClicked.


void showRewardedVideo(string location)

Use this method to present a reward video at the given location. If there is no interstitial in the cache, it will start downloading a reward video and display it right after it has finished loading.

See also hasRewardedVideo(), cacheRewardedVideo(), rewardedVideoDisplayed, rewardedVideoDismissed, rewardedVideoClosed, and rewardedVideoClicked.


void showRewardedVideo(enumeration location)

Use this method to present a reward video at the given location. If there is no interstitial in the cache, it will start downloading a reward video and display it right after it has finished loading.

See also hasRewardedVideo(), cacheRewardedVideo(), rewardedVideoDisplayed, rewardedVideoDismissed, rewardedVideoClosed, and rewardedVideoClicked.


Videos

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