Marmalade Partner Platform SDK Integration Guide

Getting Started

To get started with the integration, perform the following steps:

  1. Download the Marmalade SDK from here and follow the instructions given.
  2. Download the s3eInMobiAds extension and sample app from here.
  3. Register as a developer with InMobi.

Note: Please ensure that your application has been approved by the App Store or Play Store before entering the application URL in the InMobi publisher account.

Obtaining a Property ID

  1. Log in to your InMobi account, or click here.
  2. Click the Properties tab.
  3. Click the spanner icon next to your property. The property ID is located at the top right of the pop-up. Copy this value and use it in the integration code.

Integrating s3eInMobi Ads

Integrating with the s3eInMobiAds extension

Ensure that the InMobi extension name s3eInMobiAds is included in the sub-project section of your project file, <your project>.mkb.

If you use a version of the Marmalade SDK below 7.1.2, please follow these steps:

  1. Copy the s3eInMobiAds folder to the extensions folder of the Marmalade SDK.
  2. Copy the sample app (called s3eInMobiAds) from the Sample App folder within the extension to the examples/s3e folder of the Marmalade SDK.

Please refer to this document for a complete list of API references.

Initializing the InMobi SDK

The InMobi SDK needs to be initialized with the publisher property ID obtained from the InMobi portal using:

inmobi_initialize(const char* app_id)

Example:

inmobi_initialize(<Your app id>);

Below are examples of integrating banner and interstitial ads.

Banner Ads

Initializing Banner Ads

Use the following method to initialize and view a banner ad:

InMobiAd* inmobi_banner_init(InMobiAdsBannerType ad_type, int x, int y)

Example:

if you want to initialize an ad with ad unit 15 and position it to 100 pixels from the top, and 0 pixel from the left, use the following:

InMobiAd* testAd = inmobi_banner_init(INMOBIADS_BANNER_SIZE_320x50, 100, 0);

Loading Banner Ads

After initialization, load the banner add using inmobi_banner_load(testAd, params).

Setting Ad Request Properties While Loading a Banner Ad

Initialize a const char * with the various properties to be sent.

For example, if you want to set the gender to male, date of birth (DOB) to 16-09-1985, and refresh interval to 30, use the following:

const char* params = “age:20,income:2000”;

inmobi_banner_load(testAd, params);

Note:

  1. To receive the test ads, follow the instructions here.
  2. Date of birth must be in the dd-mm-yyyy format.
  3. After the activity starts, ad refresh will begin automatically. Note that the default refresh interval is 60 seconds. To stop refreshing ads automatically, set the refresh interval to -1 (minus one).
  4. If the publisher does not want to set any ad request parameter, pass the “” string as a parameter.

Hiding Banner Ads

Banner ads can be made invisible using:

inmobi_banner_hide(InMobiAd* ad_id)

Example:

inmobi_banner_hide(testAd);

Showing Banner Ads

Banner ads can be made visible using:

inmobi_banner_show(InMobiAd* ad_id)

Example:

inmobi_banner_show(testAd);

Changing the Original Position of a Banner Ad

The original position of a banner ad can be changed using:

inmobi_banner_move(InMobiAd* ad_id, int x, int y, int orientation)

Example:

If you want to move the banner ad to the location '250 pixels from the top and 160 pixels from the left', with landscape orientation, use the following:

inmobi_banner_move(testAd,250,160,1);

Note: It is mandatory to pass the correct device orientation for iOS apps. For Android apps, however, it can always be passed as 0.

Changing Handling Orientation

Perform the following steps:

  1. Register for orientation change callback using: s3eSurfaceRegister(S3E_SURFACE_SCREENSIZE, ScreenSizeChangeCallback, NULL);
  2. Implement a function named ScreenSizeChangeCallback to obtain new values of device width, height, and orientation. Now, using these new values, decide the new co-ordinates (x,y) of the banner ad and call inmobi_banner_move( ad_id, x, y, orientation ).

Example:

static int ScreenSizeChangeCallback(void *systemData, void *userData) {
  s3eSurfaceOrientation *obj = (s3eSurfaceOrientation *)systemData;
  if (obj->m_OrientationChanged) {
    orientation = obj->m_DeviceBlitDirection;
  }
  width    = obj->m_Width;
  height   = obj->m_Height;
  // Calculate x, y using width,height
  inmobi_banner_move(ad_id x, y, orientation);
}
		

Removing Banner Ads

A banner ad can be removed from view using:

inmobi_banner_release(InMobiAd* ad_id);

Example:

inmobi_banner_release(testAd);

Handling Callbacks for Banner Ads

To register various callbacks of banner ad view, use: InMobiAdsRegisterAdCallback(InMobiAdsCallbackAd cbid, InMobiAdsCallbackAdFn fn, void* userData, InMobiAd* ad)

Example:

To register INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED, use:

// first define a function which handles that callback
static int ad_request_completed(InMobiAd* ad, void *systemData, void *userData)
{
	// Write code to handle callback
}
// Now call InMobiAdsRegisterAdCallback passing appropriate parameters<br /><br />InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, ad_request_completed, NULL, testAd);
		

To unregister a callback of banner ad view, use:

InMobiAdsUnRegisterAdCallback(InMobiAdsCallbackAd cbid, InMobiAdsCallbackAdFn fn, InMobiAd* ad)

Example:

To unregister INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, use:

InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, int_request_completed, testAd);

Interstitial Ads

Interstitial ads occupy the full screen and are modal in nature. Interstitial ads can be in scenarios like loading an app in the background, for example.

An interstitial ad can be in one of the following states:

  • init
  • loading
  • ready
  • active
  1. The first time IMInterstitial is instantiated, the ad will be in the init state.
  2. When a request for loading the ad is made, the ad moves to the loading state.
  3. When the ad is ready to be displayed, the ad state changes to ready.
  4. At this point, a request for displaying the ad can be made.
  5. The ad moves to the active state when it is displayed to the user.
  6. When the user closes the ad, the ad moves back to the init state.

Note: You must invoke the inmobi_interstitial_load() method again before making a call to inmobi_show_interstitial().

Initializing Interstitial Ads

An interstitial ad can be initialized using:

inmobi_interstitial_init();

Example:

inmobi_interstitial_init();

Loading Interstitial Ads

After initializing, the interstitial ad can be loaded using:

inmobi_interstitial_load(const char* params);

Setting Various Ad Request Properties while Loading Interstitial Ads

Same as setting ad request properties while loading banner ads. Please see here for details.

Showing Interstitial Ads

Upon getting the callback “INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED”, an interstitial ad can be displayed using:

inmobi_interstitial_show();

Removing Interstitial Ads

An interstitial ad can be removed using:

inmobi_interstitial_release();

Handling Callbacks for Interstitial Ads

To register various callbacks for the interstitial ad view, use:

InMobiAdsRegisterIntCallback(InMobiAdsCallbackInt cbid, InMobiAdsCallbackIntFn fn, void* userData)

Example:

To register INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, use the following:

// First, define a function that handles that callback
static int int_request_completed(void *systemData, void *userData)
{
	// Write code to handle callback
}
// Now, call InMobiAdsRegisterIntCallback passing appropriate parameters
InMobiAdsRegisterIntCallback(INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, int_request_completed, NULL);
		

To unregister a callback, use:

InMobiAdsUnRegisterIntCallback(InMobiAdsCallbackAd cbid, InMobiAdsCallbackAdFn fn);

Example:

To unregister INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, use the following:

InMobiAdsUnRegisterIntCallback(INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, int_request_completed);

Note:

Marmalade has a limitation in Android devices: the current activity is paused as soon as a new activity is pushed over it. So, the publisher’s activity will not be able to receive callback INMOBIADS_CALLBACK_INT/AD_SHOW_ADSCREEN in case of interstitial or two-piece ads.

However, when an interstitial or two-piece ad is about to appear, S3E_DEVICE_PAUSE callback is received, if registered. So, the work-around for this limitation is to register S3E_DEVICE_PAUSE using s3eDeviceRegister(), and then implement a function to handle this callback.

Example:

// Register for callback using:
s3eDeviceRegister(S3E_DEVICE_PAUSE, DeviceStateChangeCallback, NULL);
// Define a function to handle the callback
static int DeviceStateChangeCallback(void *systemData, void *userData)
{
	return S3E_RESULT_SUCCESS;
}
		

Integrating InMobi Analytics

To call the InMobi analytics method in your app, first call the inmobi_initialize method.

To get the InMobi analytics method list, please refer to the InMobi API specification document, here.

Example

include "s3e.h"
#include "ExamplesMain.h"
#include "s3eInMobiAds.h"
#include <string>
#include <iostream>
#include <map>
#include <iostream>
#include <utility>
static Button* g_Blank;
static Button* g_InitOrReleaseBanners;
static Button* g_LoadBannerTop;
static Button* g_LoadBannerBottom;
static Button* g_HideOrShowBanners;
static Button* g_ExchangeBanners;
static Button* g_InitOrReleaseInterstitial;
static Button* g_LoadInterstitial;
static Button* g_ShowInterstitial;
const char *test_publisher_id = "<Your InMobi Site ID here>";
static bool banners_initialized, banners_hidden, int_initialized;
const char *AdRequestParams = "age:25,education:EDUCATION_HIGHSCHOOLORLESS";
static InMobiAd *top_ad;
static int top_ad_pos_x, top_ad_pos_y;
static InMobiAd *bottom_ad;
static int bottom_ad_pos_x, bottom_ad_pos_y;
static int width, height, orientation;
/**
* Banner Ad Callbacks.
*/
static int ad_request_completed(InMobiAd* ad, void *systemData, void *userData) {
s3eDebugOutputString("Callback function - INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED");
return S3E_RESULT_SUCCESS;
}
static int ad_request_failed(InMobiAd* ad, void *systemData, void *userData) {
char *error = (char *)systemData;
std::string str = "Callback function - INMOBIADS_CALLBACK_AD_REQUEST_FAILED - Error: ";
str.append(error);
const char * outputString = str.c_str();
s3eDebugOutputString(outputString);
return S3E_RESULT_SUCCESS;
}
static int ad_show_adscreen(InMobiAd* ad, void *systemData, void *userData) {
s3eDebugOutputString("Callback function - INMOBIADS_CALLBACK_AD_SHOW_ADSCREEN");
return S3E_RESULT_SUCCESS;
}
static int ad_dismiss_adscreen(InMobiAd* ad, void *systemData, void *userData) {
s3eDebugOutputString("Callback function - INMOBIADS_CALLBACK_AD_DISMISS_ADSCREEN");
return S3E_RESULT_SUCCESS;
}
static int ad_leave_application(InMobiAd* ad, void *systemData, void *userData) {
s3eDebugOutputString("Callback function - INMOBIADS_CALLBACK_AD_LEAVE_APPLICATION");
return S3E_RESULT_SUCCESS;
}
static int ad_interacted(InMobiAd* ad, void *systemData, void *userData){ 
s3eDebugOutputString("Callback function - INMOBIADS_CALLBACK_AD_INTERACTED");
return S3E_RESULT_SUCCESS;
}
/**
* Interstitial Ad Callbacks.
*/
static int int_request_completed(void *systemData, void *userData) {
s3eDebugOutputString("Callback function() - INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED;");
return S3E_RESULT_SUCCESS;
}
static int int_request_failed(void *systemData, void *userData) {
const char *error = (const char *)systemData;
std::string str = "Callback function() - INMOBIADS_CALLBACK_AD_REQUEST_FAILED - Error: ";
str.append(error);
const char * outputString = str.c_str();
s3eDebugOutputString(outputString);
return S3E_RESULT_SUCCESS;
}
static int int_show_adscreen(void *systemData, void *userData) {
s3eDebugOutputString("Callback function() - INMOBIADS_CALLBACK_INT_SHOW_ADSCREEN;");
return S3E_RESULT_SUCCESS;
}
static int int_dismiss_adscreen(void *systemData, void *userData) {
s3eDebugOutputString("Callback function() - INMOBIADS_CALLBACK_INT_DISMISS_ADSCREEN;");
return S3E_RESULT_SUCCESS;
}
static int int_leave_application(void *systemData, void *userData) {
s3eDebugOutputString("Callback function() - INMOBIADS_CALLBACK_INT_LEAVE_APPLICATION;");
return S3E_RESULT_SUCCESS;
}
static int int_ad_interacted(void *systemData, void *userData) {
s3eDebugOutputString("Callback function() - INMOBIADS_CALLBACK_INT_INTERACTED;");
return S3E_RESULT_SUCCESS;
}
static int ScreenSizeChangeCallback(void *systemData, void *userData) {
s3eSurfaceOrientation *obj = (s3eSurfaceOrientation *)systemData;
if (obj->m_OrientationChanged) {
orientation = obj->m_DeviceBlitDirection;
}
width = obj->m_Width;
height = obj->m_Height;
top_ad_pos_x = 0;
top_ad_pos_y = 0;
bottom_ad_pos_x = width - 320;
bottom_ad_pos_y = height - 50;
inmobi_banner_move(top_ad, top_ad_pos_x, top_ad_pos_y, orientation);
inmobi_banner_move(bottom_ad, bottom_ad_pos_x, bottom_ad_pos_y, orientation);
return S3E_RESULT_SUCCESS;
}
static int DeviceStateChangeCallback(void *systemData, void *userData)
{
/*
*write code to handle INMOBIADS_CALLBACK_AD/INT_SHOW_ADSCREEN in case of interstitial/two-piece on Android devices
*/
return S3E_RESULT_SUCCESS;
void ExampleInit() {
if (!s3eInMobiAdsAvailable()) {
s3eDebugOutputString("Error - InMobiAds extension not available.");
}
/**
* Initializing variables.
*/
top_ad = bottom_ad = 0;
banners_initialized = false;
banners_hidden = false;
int_initialized = false;
orientation = 0;
width = s3eSurfaceGetInt(S3E_SURFACE_WIDTH);
height = s3eSurfaceGetInt(S3E_SURFACE_HEIGHT);
orientation = s3eSurfaceGetInt(S3E_SURFACE_DEVICE_BLIT_DIRECTION);
top_ad_pos_x = 0;
top_ad_pos_y = 0;
bottom_ad_pos_x = width - 320;
bottom_ad_pos_y = width - 50;
s3eSurfaceRegister(S3E_SURFACE_SCREENSIZE, ScreenSizeChangeCallback, NULL);
/*
* Register for this callback to receive S3E_DEVICE_PAUSE callback in place of INMOBIADS_CALLBACK_AD/INT_SHOW_ADSCREEN in case of interstitial/ two piece ads on android devices
*/
3eDeviceRegister(S3E_DEVICE_PAUSE, DeviceStateChangeCallback, NULL);
/**
* Initializing buttons.
*/
g_Blank = NewButton("");
g_InitOrReleaseBanners = NewButton("Init/Release BannerAds");
g_LoadBannerTop = NewButton("Load BannerAd (Top)");
g_LoadBannerBottom = NewButton("Load BannerAd (Bottom)");
g_HideOrShowBanners = NewButton("Hide/Show BannerAds");
g_ExchangeBanners = NewButton("Exchange Banner Ads");
g_InitOrReleaseInterstitial = NewButton("Init/Release IntAd");
g_LoadInterstitial = NewButton("Load InterstitialAd");
g_ShowInterstitial = NewButton("Show InterstitialAd");
g_Blank = NewButton("");
/**
* Initialize Ad Request Parameters here.
*/
// Setting InMobi log level
inmobi_set_loglevel(1);
// Initializing the InMobi SDK
inmobi_initialize(test_publisher_id);
// Starting a section
analytics_beginSection("testSection");
// Ending the section
analytics_endSection("testSection");
}
void ExampleTerm() {
DeleteButtons();
}
void registerAdCallbacks(InMobiAd* ad) {
InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED, ad_request_completed, NULL, ad);
InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_AD_REQUEST_FAILED, ad_request_failed, NULL, ad);
InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_AD_SHOW_ADSCREEN, ad_show_adscreen, NULL, ad);
InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_AD_DISMISS_ADSCREEN, ad_dismiss_adscreen, NULL, ad);
InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_AD_LEAVE_APPLICATION, ad_leave_application, NULL, ad);
InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_AD_INTERACTED, ad_interacted, NULL, ad);
}
void unregisterAdCallbacks(InMobiAd* ad) {
InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED, ad_request_completed, ad);
InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_AD_REQUEST_FAILED, ad_request_failed, ad);
InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_AD_SHOW_ADSCREEN, ad_show_adscreen, ad);
InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_AD_DISMISS_ADSCREEN, ad_dismiss_adscreen, ad);
InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_AD_LEAVE_APPLICATION, ad_leave_application, ad);
InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_AD_INTERACTED, ad_interacted, ad);
}
bool ExampleUpdate()
{
Button* pressed = GetSelectedButton();
if (pressed && pressed == g_InitOrReleaseBanners) {
if (!banners_initialized) {
banners_initialized = true;
top_ad = inmobi_banner_init(test_publisher_id, INMOBIADS_BANNER_SIZE_320x50,
top_ad_pos_x, top_ad_pos_y);
inmobi_banner_disable_hardware_acceleration(top_ad); //Only applicable for Android
registerAdCallbacks(top_ad);
bottom_ad = inmobi_banner_init(test_publisher_id, INMOBIADS_BANNER_SIZE_320x50,
bottom_ad_pos_x, bottom_ad_pos_y);
inmobi_banner_disable_hardware_acceleration(bottom_ad); //Only applicable for Android
registerAdCallbacks(bottom_ad);
} else {
banners_initialized = false;
inmobi_banner_release(top_ad); top_ad = 0;
unregisterAdCallbacks(top_ad);
inmobi_banner_release(bottom_ad); bottom_ad = 0;
unregisterAdCallbacks(bottom_ad);
}
}
else if(pressed && pressed == g_LoadBannerTop) {
inmobi_banner_load(top_ad, AdRequestParams);
}
else if(pressed && pressed == g_LoadBannerBottom) {
inmobi_banner_load(bottom_ad, AdRequestParams);
}
else if (pressed && pressed == g_HideOrShowBanners) {
if (banners_hidden) {
banners_hidden = false;
inmobi_banner_show(top_ad);
inmobi_banner_show(bottom_ad);
} else {
banners_hidden = true;
inmobi_banner_hide(top_ad);
inmobi_banner_hide(bottom_ad);
}
}
else if (pressed && pressed == g_ExchangeBanners) {
inmobi_banner_move(top_ad, bottom_ad_pos_x, bottom_ad_pos_y, orientation);
inmobi_banner_move(bottom_ad, top_ad_pos_x, top_ad_pos_y, orientation);
InMobiAd *temp = bottom_ad; bottom_ad = top_ad; top_ad = temp;
}
else if(pressed && pressed == g_InitOrReleaseInterstitial) {
if (!int_initialized) {
int_initialized = true;
inmobi_interstitial_init(test_publisher_id);
InMobiAdsRegisterIntCallback(INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, int_request_completed, NULL);
InMobiAdsRegisterIntCallback(INMOBIADS_CALLBACK_INT_REQUEST_FAILED, int_request_failed, NULL);
InMobiAdsRegisterIntCallback(INMOBIADS_CALLBACK_INT_SHOW_ADSCREEN, int_show_adscreen, NULL);
InMobiAdsRegisterIntCallback(INMOBIADS_CALLBACK_INT_DISMISS_ADSCREEN, int_dismiss_adscreen, NULL);
InMobiAdsRegisterIntCallback(INMOBIADS_CALLBACK_INT_LEAVE_APPLICATION, int_leave_application, NULL);
InMobiAdsRegisterIntCallback(INMOBIADS_CALLBACK_INT_INTERACTED, int_ad_interacted, NULL);
} else {
int_initialized = false;
inmobi_interstitial_release();
InMobiAdsUnRegisterIntCallback(INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, int_request_completed);
InMobiAdsUnRegisterIntCallback(INMOBIADS_CALLBACK_INT_REQUEST_FAILED, int_request_failed);
InMobiAdsUnRegisterIntCallback(INMOBIADS_CALLBACK_INT_SHOW_ADSCREEN, int_show_adscreen);
InMobiAdsUnRegisterIntCallback(INMOBIADS_CALLBACK_INT_DISMISS_ADSCREEN, int_dismiss_adscreen);
InMobiAdsUnRegisterIntCallback(INMOBIADS_CALLBACK_INT_LEAVE_APPLICATION, int_leave_application);
InMobiAdsUnRegisterIntCallback(INMOBIADS_CALLBACK_INT_INTERACTED, int_ad_interacted);
}
}
else if(pressed && pressed == g_LoadInterstitial) {
inmobi_interstitial_load(AdRequestParams);
}
else if(pressed && pressed == g_ShowInterstitial) {
inmobi_interstitial_show();
}
return true;
}
void ExampleRender()
{
}
		

On This Page

Last Updated on: 02 May, 2016