Integrating ads into your app

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

To see a sample application that shows you how to use the Advertising Service APIs, download the Banner Ads app in the Platform section of the Cascades Samples repository. After you download the sample, read the readme.txt file for information about running the sample app.

Before you begin

Before you can integrate ads into your application, you need to create a project, and make some changes to the .pro and bar-descriptor.xml files in your application. For more information, see Create a new project.

To modify the .pro file:

In the Project Explorer view, open the your_project_name.pro file, and add the following statement to the file.

LIBS += -lbbcascadesadvertisement

To modify the bar-descriptor.xml file:

  1. In the Project Explorer view, open the bar-descriptor.xml file, and select Device Identifying Information. The Advertising Service SDK needs an anonymous unique identifier for each ad request.
  2. You can also select GPS Location if the user agrees to provide this information. The Advertising Service can use the geolocation to deliver appropriate ads to the user.

Creating an ad banner

When you create an ad banner, you can specify the following properties that define the banner.

zoneId

Identifies your application to the Advertising Service. The trial zone ID is 117145. This property is required.

refreshRate

Specifies the interval in seconds at which the application makes ad requests. 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 application attempts to load if 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://ci0000001175706/placeholder_728x90.png).

backgroundColor

Specifies the color that appears while the application 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.

Create the ad banner using QML

To access Banner class in QML, you need to import the library containing the Banner class.

import bb.cascades.advertising 1.0

When you import the library, you can use the Banner class like any other QML component. Here's an example that creates a banner and adds it to a page.

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
                 }
             }
     }

Create the ad banner using C++

To use the Banner class in C++, you need to include the Banner class and specify the using directive for the advertisement library.

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

When you include the Banner class, you instantiate Banner and set its properties. Here's an example that creates a banner and adds it to a page.

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);

Here's what a banner looks like with the properties specified in the code sample.

Example of a banner with the properties specified in the code sample.

Last modified: 2014-09-29



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

comments powered by Disqus