Integrating an ad into your Cascades app

The Advertising Service API provides the functionality that your app can use to perform key tasks, such as creating an ad banner, setting the banner's size, position, and refresh rate, and displaying the ad banner.

To see a sample app that shows you how to use the Advertising Service APIs, download the Banner Ads app. After you download the sample, read the readme.txt file for information about running the sample app.

Prerequisites

To use the Advertising Service APIs in your app, you need to link against the correct library by adding the following line to your project's .pro file:

LIBS += -lbbcascadesadvertisement

Your app must also have the Device Identifying Information permission ( read_device_identifying_ information), which you specify in the bar-descriptor.xml file for your app.

You can also add the GPS Location permission ( read_geolocation). The Advertising Service can use the geolocation to deliver appropriate ads to the user.

To use the Advertising Service APIs in your QML app, you must register the Banner class. For example, in your main.cpp file, you can add the following code:

#include<bb/cascades/advertisement/Banner>
using namespace bb::cascades::advertisement;

Q_DECL_EXPORT int main(int argc, char **argv)
{
    Application app(argc, argv);

    // ... 

    qmlRegisterType<bb::cascades::advertisement::Banner>(
        "bb.cascades.advertisement", 1, 0, "Banner");

    // ...
}

Create an ad banner

When you create an ad banner, you can specify the following properties:

  • zoneId: Identifies your app to the Advertising Service. The trial zone ID is 117145. This property is required.
  • refreshRate: Specifies the interval at which the app makes ad requests in seconds. The default is 60 seconds.
  • preferredWidth and preferredHeight: Specify the size of the ad banner. These properties are required.
  • transitionsEnabled: Enables the banner to fade-in in slow motion when transitions are set to true.
  • placeHolderURL: Specifies the placeholder image that the app tries to load when it can't load the banner because of network problems or some other problem. The placeholder image can be local (for example, asset:///placeholder_728x90.png) or remote (for example, http://yourcompany/placeholder_728x90.png).
  • backgroundColor: Specifies the color that appears while the app refreshes the banner. If you specify a background color and placeholder image together, the placeholder image takes precedence, and is loaded instead of the background color.
  • borderColor: Specifies the color of the border around the ad. The default color is blue.
  • borderWidth: Specifies the width of the border around the ad. The border width must be an integer value from 0 to 10 pixels.
  • horizontalAlignment: Specifies the horizontal alignment of the ad.

Example of a banner with the properties specified in the code sample.The following code samples create the ad banner shown in the image to the right.

import bb.cascades 1.4
import bb.cascades.advertisement 1.0

Page {
   Container {
        Banner {
            zoneId: 117145
            refreshRate: 60
            preferredWidth: 300
            preferredHeight: 50
            transitionsEnabled: true
            placeHolderURL: "<asset:///placeholder_728x90.png>"
            backgroundColor: Color.Green
            borderColor: Color.Blue
            borderWidth: 2
            horizontalAlignment: HorizontalAlignment.Center
        }
    }
}
#include <bb/cascades/advertisement/Banner>
using namespace bb::cascades::advertisement;

page1 = Page().create();
container1 = Container().create();

Banner *banner1 = new Banner();
banner1->setZoneId(117145);
banner1->setRefreshRate(60);
banner1->setPreferredWidth(320);
banner1->setPreferredHeight(50);
banner1->setTransitionsEnabled(true);
banner1->setPlaceHolderURL(QUrl("asset:///placeholder_728x90.png"));
banner1->setBackgroundColor(Color::Green);
banner1->setBorderColor(Color::Gray);
banner1->setBorderWidth(2);
banner1->setHorizontalAlignment(HorizontalAlignment::Center);

container1->add(banner1);
page1->setContent(container1);

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus