Integrating an ad into your application

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

To see a sample application that shows you how to use the Advertising Service API, visit the Samples repository and download the AdSample sample app. After you download the sample, read the readme.txt file for information about running the sample app.

Set up your project

Before you get started, make sure that you set up your development environment correctly, that you have a BlackBerry 10 device or simulator ready for testing, and that you imported the sample project into your workspace. Getting started has all the information you need to configure your environment.

To import and run the sample application:

  1. Download the sample from the Samples repository. You can either clone the Git repository or download a zip file of the entire repository and unzip it.
  2. To launch the Momentics IDE for BlackBerry, from the Start menu, click on BlackBerry Native SDK.
  3. On the File menu, click Import.
  4. Expand General, and select Existing Projects into Workspace. Click Next.
  5. Browse to the location where you saved your sample app, and then click OK. The sample project should be displayed in the Projects section.
  6. Click Finish to import the project into your workspace.
  7. In the Project Explorer pane, right-click AdSample and depending on whether you are deploying to a device or simulator, select either Build Configurations > Set Active > Device-Debug or Build Configurations > Set Active > Simulator-Debug.
  8. In the Project Explorer pane, right-click AdSample and select Build Project.
  9. In the Project Explorer pane, right-click AdSample and select Debug As > BlackBerry C/C++ Application.

Display an ad banner on a screen

The following code samples show how the sample application 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>
Set the constants defining the zone ID, size, and position of the ad banner as follows. The x and y positions define the horizontal and vertical distances from the top-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 application 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 application, 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 out to stderr. The application exits 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 BlackBerryfrom 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(). Note that 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 application.
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(). Note that you can call bbads_banner_set_placeholder_url() only before the ad banner is loaded and that the most recent call replaces the previously set URL. The URL must be local (file://...). If the application can't load the ad banner because of a bad network connection or some other problem, the application tries to load the placeholder image. If the application can't load the placeholder image because of network problems or because the URL is not local, 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 application calls bbads_banner_request_events(). The call registers the application 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 application checks the event to see if it came from the bbads event domain. The sample application 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 web page. When this event occurs, the sample application 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: 2013-12-21

comments powered by Disqus