Integrating an ad into your C app

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

Advertising Service event handling is done through BlackBerry Platform Services (BPS). For information about BPS, visit the BlackBerry Platform Services Library page.

To see a sample app that shows you how to use the Advertising Service API, download the Ad Sample sample 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 Advertising Service (libbbads) to your project.

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.

Display an ad banner on a screen

The following code samples show how the sample app uses the Advertising Service API to display an ad banner on a screen.

You must include the following header files:

#include <bbads/bbads.h>
#include <bbads/event.h>

First, you must set the constants defining the zone ID, size, and position of the ad banner. The x and y positions define the horizontal and vertical distances from the upper-left corner of the screen, respectively. If your app allows both portrait and landscape orientation, check that these measurements are suitable for both, or use different values for each. All measurements are in pixels. You must change the BANNER_TEST_ZONE_ID to your unique zone ID before you publish your app on BlackBerry World.

// Ad Banner parameters   
static const int BANNER_TEST_ZONE_ID = 117145;   
static const int BANNER_SIZE_X = 468;   
static const int BANNER_SIZE_Y = 60;   
static const int BANNER_POSITION_X = 180;   
static const int BANNER_POSITION_Y = 150;

The app uses the bbads_banner_t object to display the ad banner, and the ad_is_visible variable to specify the initial visibility of the ad banner (0 for hidden, 1 for visible). By default, the object does not contain an ad banner.

bbads_banner_t* ad_banner = 0;
int ad_is_visible = 0;

To create the ad banner, call bbads_banner_create(), and pass the top-level screen in the app, the group name of the top-level screen, and the zone ID as the arguments. The handle of the ad banner is returned in ad_banner. If the function can't create the ad banner, an error is returned and an error message is printed to stderr. The app closes with a value of -1.

if (BBADS_EOK != bbads_banner_create(&ad_banner, screen_window, 
          window_group_name, BANNER_TEST_ZONE_ID)) { 
    fprintf(stderr, "ERROR: bbads_banner_create failed!\n"); 
    return -1; 
}

The following error codes for ad banner creation are declared in the bbads.h file. You can use these error codes to determine the specific type of error that occurred. You can access the bbads.h file in the Momentics IDE for BlackBerry from the Outline view.

typedef enum
{
   /* Success. */ 
   BBADS_EOK = 0,

   /* Invalid banner provided. */ 
   BBADS_EBANNER = 1, 

   /* Invalid size. */ 
   BBADS_ESIZE = 2, 

   /* Invalid parameter provided. */ 
   BBADS_EINVAL = 3, 

   /* Invalid state to perform requested operation.*/ 
   BBADS_ESTATE = 4, 

   /* Insufficient memory to fulfill requested operation. */ 
   BBADS_ENOMEM = 5, 

   /* Internal error. The requested operation was not */
   /* fulfilled. */ 
   BBADS_EINTERNAL = 127 

 } bbads_error_t; 

To set the size of the ad banner, call bbads_banner_set_size(). You must call this function before the ad banner is loaded. The ad network tries to fill the ad banner with the size that you specify. If the function can't set the size of the ad banner, load_ad_failure() destroys the ad banner and returns an error code. The function load_ad_failure() is a part of the sample app.

if (BBADS_EOK != bbads_banner_set_size(ad_banner, BANNER_SIZE_X, 
          BANNER_SIZE_Y))
    load_ad_failure();

To set the position of the ad banner, call bbads_banner_set_position().

if (BBADS_EOK != bbads_banner_set_position(ad_banner, 
          BANNER_POSITION_X, BANNER_POSITION_Y))
{
	fprintf(stderr, "set position failed\n");
	load_ad_failure();
}

To specify the local URL for a placeholder image for the ad banner, call bbads_banner_set_placeholder_url(). You can call bbads_banner_set_placeholder_url() only before the ad banner is loaded. The most recent call replaces the previously set URL. The URL must be local (file://...). If the app can't load the ad banner because of a bad network connection or some other problem, the app tries to load the placeholder image. If the app can't load the placeholder image, a transparent ad banner is created.

if (BBADS_EOK != bbads_banner_set_placeholder_url(ad_banner, 
          get_banner_placeholder_image_url()))
{
	fprintf(stderr, "set placeholder failed\n");
	load_ad_failure();
} 

To specify the time in seconds between ad refreshes, call bbads_banner_set_refresh_rate(). The minimum refresh rate is 60 seconds, which is also the default value. You can call this function only before the ad banner is loaded.

if (BBADS_EOK != bbads_banner_set_refresh_rate(ad_banner, 60))  
{
	fprintf(stderr, "set refresh rate failed\n");
	load_ad_failure();
}

To set the width of the border, call bbads_banner_set_border_width(). The calculation to determine the overall ad banner width and height, based on the border width, is described in the bbads.h header file. You can call this function only before the ad banner is loaded.

if (BBADS_EOK != bbads_banner_set_border_width(ad_banner, 2))  
{
	fprintf(stderr, "set border width failed\n");
	load_ad_failure();
} 

To display the ad banner on the screen that you created using bbads_banner_create(), call bbads_banner_load().

if (BBADS_EOK != bbads_banner_load(ad_banner)) 
{
	fprintf(stderr, "load failed\n");
	load_ad_failure();
}

Handle an asynchronous event

To activate event delivery through the BlackBerry Platform Services (BPS) for an ad banner, the sample app calls bbads_banner_request_events(). The call registers the app for asynchronous event delivery, and passes in the ad banner.

if (BBADS_EOK != bbads_banner_request_events(ad_banner)) 
{
    fprintf(stderr, "request events failed\n");
    load_ad_failure();
} 

In main(), the sample app checks the event to see if it came from the bbads event domain. The sample app then extracts some information about the event, and calls banner_event_handler() to handle the event.

if (bbads_get_domain() == bps_event_get_domain(event))
{ 
  bbads_banner_t* event_banner;
  bbads_event_get_banner(event, &event_banner);
  bbads_banner_event_type_t event_type = (bbads_banner_event_type_t)
        bps_event_get_code(event);
  banner_event_handler(event_banner, event_type);
}

When the user taps the ad banner, the browser opens and loads the target webpage. When this event occurs, the sample app receives the notification of the BBADS_EVENT_NAVIGATING event type, and the event handler displays a message indicating that it is handling the event.

void banner_event_handler(bbads_banner_t* banner, 
     bbads_banner_event_type_t type)  
{  
    if (BBADS_EVENT_NAVIGATING == type)  
       fprintf(stderr, "Handling BBADS_EVENT_NAVIGATING event.\n");  
}

To stop receiving asynchronous events for an ad banner, call screen_stop_events(screen_context).

When the app is closed, you must clean up resources.

if (navigator_get_domain() == bps_event_get_domain(event)){
    int code = bps_event_get_code(event);

    if (NAVIGATOR_EXIT == code) {
        if (BBADS_EOK != bbads_banner_destroy(ad_banner)) {
            fprintf(stderr, "cannot destroy banner\n");
        } else {
            fprintf(stderr, "banner destroy\n");
        }
        exit_application = 1;
    }     
}

Last modified: 2014-09-30



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

comments powered by Disqus