Marmalade Partner Platform Interface API Specification

Methods for Integrating Ads

Method Signature

s3eResult inmobi_initialize(const char* app_id)

Method Description

This API is used to initialize the InMobi SDKs with the publisher app ID obtained from the InMobi portal.

Parameter Descriptions

  • app_id : (const char*) Value for app_id. This is the InMobi app ID provided at the time of registration.

Return Value

S3E_RESULT_SUCCESS

The operation is successfully completed.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_initialize(<YOUR APP ID>);

Method Signature

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

Method Description

This API is used to initialize the banner ad view, and set the banner ad properties like AppId, AdType, and position of the adView, that is, top-left coordinates(all passed in arguments). It also adds the banner ad view to the publisher’s activity. It returns an ID that should be saved to perform further operations on the banner ad.

Parameter Descriptions

  1. ad_type : (InMobiAdsBannerType) Values for ad_type:
    • INMOBIADS_BANNER_SIZE_300x250 - Medium Rectangle size, ad size equivalent to this slot is 300 X 250
    • INMOBIADS_BANNER_SIZE_728x90 - Leaderboard size for iPad, ad size equivalent to this slot is 728 X 90
    • INMOBIADS_BANNER_SIZE_468x60 - Full Banner size for iPad, ad size equivalent to this slot is 468 X 60
    • INMOBIADS_BANNER_SIZE_120x600 - Skyscraper size, ad size equivalent to this slot is 120 X 600
    • INMOBIADS_BANNER_SIZE_320x50 - Default ad size, ad size equivalent to this slot is 320 X 50
  1. x (int) - Pixels from top of the device.
  2. y : (int) - Pixels from left of the device.

Return Value

ad_id : (InMobiAd* ) Value for ad_id that should be saved and used to perform further operations on it.

Usage example

InMobiAd* ad_id = inmobi_banner_init(INMOBIADS_BANNER_SIZE_320x50, 0, 0);

Method Signature

s3eResult inmobi_banner_load(InMobiAd* ad, const char* params)

Method Description (Android ONLY)

This API is used to disable the hardare acceleration. However, we recommend that you do not disable the hardware acceleration, as it results in bad user experience when HTML5 videos are being played. This is an optional method. You can disable this feature at the code level, before calling the inmobi_banner_load method. It takes the value of the ID returned by method inmobi_banner_init() as the only argument.

Parameter Descriptions

ad: (InMobiAd*) This ad ID value is returned by inmobi_banner_init()

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_banner_disable_hardware_acceleration(ad_id);

Method Signature

s3eResult inmobi_banner_load(InMobiAd* ad, AdRequestParams* params)

Method Description

This API is used to set the ad request properties for a banner ad, to load it, and to display it on the publisher screen. It takes the ID returned by method inmobi_banner_init() as the first argument and AdRequest parameters as the other argument.

Parameter Descriptions

  1. ad: (InMobiAd*) This ad ID value is returned by inmobi_banner_init()
  2. params: (const char *) These can be set as follows. Also, an empty string “” can be passed in case publisher the does not want to set any parameter.

AdRequest Parameters

  1. postalCode : (const char*)
  2. areaCode : (const char*)
  3. dateOfBirth : (const char*)
  4. gender : (const char*)<br />

    Values for GenderType:

    • GENDER_MALE
    • GENDER_FEMALE
    • GENDER_UNKNOWN
  5. keywords: (const char*)
  6. deviceIdMask: ((const char*))

    Values for deviceIdMask:
    iOS

    • EXCLUDE_ODIN1
    • EXCLUDE_FB_ATTR_ID
    • EXCLUDE_VENDOR_ID
    • EXCLUDE_ADVERTISER_ID

    Android

    • EXCLUDE_UM5
    • EXCLUDE_ODIN1
    • EXCLUDE_FB_ATTR_ID
  7. income: (number)
  8. education: (const char*)<br />Values for education:
    • EDUCATION_HIGHSCHOOLORLESS
    • EDUCATION_COLLEGEORGRADUATE
    • EDUCATION_POSTGRADUATEORABOVE
    • EDUCATION_UNKNOWN
  9. ethnicity: (const char*)

    Values for ethnicity:

    • ETHNICITY_HISPANIC
    • ETHNICITY_CAUCASIAN
    • ETHNICITY_ASIAN
    • ETHNICITY_AFRICANAMERICAN
    • ETHNICITY_OTHER
    • ETHNICITY_UNKNOWN
  1. age : (int)
  2. interests : (const char*)
  3. loginID : (const char*)
  4. sessionID : (const char*)
  5. city: (const char*)
  6. state: (const char*)
  7. country: (const char*)
  8. userLatitude: (double) (iOS only)
  9. userLongitude: (double) (iOS only)
  10. accuracy:(double) (iOS only)
  11. refreshInterval: (int)
  12. locationqueryallowed: (const char*)(Android only)
    Values for locationqueryallowed:
    • TRUE
    • FALSE
  13. language: (const char*)
  14. refTagKey: (const char*)
  15. refTagValue: (const char*)
  16. animation:(InMobiAdsAnimationType)

    Values for animation:
    iOS

    • ANIMATION_OFF
    • ANIMATION_FLIPFROMLEFT
    • ANIMATION_FLIPFROMRIGHT
    • ANIMATION_CURLUP
    • ANIMATION_CURLDOWN

Android

      • ANIMATION_OFF
      • ANIMATION_ROTATE_HORIZONTAL
      • ANIMATION_ROTATE_VERTICAL
      • ANIMATION_Alpha

Note: refreshInterval and animation are applicable for Banner ads only.

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

const char * params = “age:20, keywords:inmobi”;

inmobi_banner_load(ad_id, params);

Method Signature

s3eResult inmobi_banner_show(InMobiAd* ad)

Method Description

This API is used to make a banner ad visible, if hidden, on the publisher screen. It takes ad_id as argument returned by inmobi_banner_init().

Parameter Descriptions

ad: (InMobiAd*) ad_id returned by inmobi_banner_init()

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

inmobi_banner_show(ad_id);

Method Signature

s3eResult inmobi_banner_hide(InMobiAd* ad)

Method Description

This API is used to hide a banner ad (if visible already) on the publisher screen. It takes ad_id as argument returned by inmobi_banner_init()

Parameter Descriptions

ad: (InMobiAd*) ad_id is returned by inmobi_banner_init()

Return Value

S3E_RESULT_SUCCESS

The operation is successfully completed.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_banner_hide(ad_id);

Method Signature

s3eResult inmobi_banner_move(InMobiAd* ad, int x, int y, int orientation)

Method Description

This API is used to move a banner ad to a particular position on the publisher screen. It takes ad_id as an argument returned by inmobi_banner_init(). The second and third arguments are top-left co-ordinates of publisher screen for new position of banner ad. The fourth argument is the new device orientation.

Parameter Descriptions

(InMobiAd*) ad_id returned by inmobi_banner_init()
x: (int) left co-ordinate of the publisher screen for new position of banner ad.
y: (int) top co-ordinate of the publisher screen for new position of banner ad.
orientation: (int) device orientation

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_banner_move(ad_id,100,0,1);

Note: The orientation is required for iOS only as this parameter is ignored for android.

Method Signature

s3eResult inmobi_banner_release(InMobiAd* ad)

Method Description

This API is used to remove a banner ad from the publisher screen. It takes ad_id as argument returned by inmobi_banner_init().

Parameter Descriptions

ad: (InMobiAd*) ad_id is returned by inmobi_banner_init()

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_banner_release(ad_id);

Method Signature

s3eResult inmobi_interstitial_init()

Method Description

This API is used to initialise an interstitial ad. It instantiates the interstitial ad and sets the appId (passed in argument).

Parameter Descriptions

No arguments required

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_interstitial_init();

Method Signature

s3eResult inmobi_interstitial_disable_hardware_acceleration()

Method Description (Android ONLY)

This API is used to disable hardware acceleration .However, we recommend not to disable hardware acceleration as bad user experience may be caused if HTML5 video is played.It is a optional method , For making this feature working .You can disable this feature at the code level but before calling the inmobi_interstitial_load method.

Parameter Descriptions

No arguments required

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_interstitial_disable_hardware_acceleration();

Method Signature

s3eResult inmobi_interstitial_load(const char * params)

Method Description

This API is used to set the ad request properties for an interstitial ad and load it. It takes the AdRequest Parameters as argument.

Parameter Descriptions

params: (const char *)These can be set as described in banner Ads section. Also, “” can be passed in case publisher does not want to set any parameter.

Usage example

const char * params = “age:20, keywords:inmobi”;

inmobi_interstitial_load(ad_id,¶ms);

Method Signature

s3eResult inmobi_interstitial_show()

Method Description

This API is used to display the interstitial ad once it has been loaded and is ready to be displayed.

Parameter Descriptions

No arguments required

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_interstitial_show();

Method Signature

s3eResult inmobi_interstitial_release()

Method Description

This API is used to release the interstitial ad which was requested for earlier by the Publisher.

Parameter Descriptions

No arguments required

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_interstitial_release();

Method Signature

s3eResult inmobi_set_loglevel(int loglevel)

Method Description

This API is used to set the log level for printing console messages

Parameter Descriptions

loglevel: (int) log level to be set in InMobi SDK

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

inmobi_set_loglevel(loglevel);

Log Levels:

  • 2 - log level used for verbose logging
  • 1 - log level used for debugging logging
  • 0 - default minimal log level

Method Signature

const char* inmobi_get_version()

Method Description

This API is used to get the version of this extension “s3eInMobiAds”.

Parameter Descriptions

No arguments required

Return Value

version_string: (const char*) version string which contains the version of the s3eInMobiAds extension.

Usage example

char *version_string = inmobi_get_version();

Methods for Registering/Unregistering CallBacks

Method Signature

s3eResult InMobiAdsRegisterAdCallback(InMobiAdsCallbackAd cbid, InMobiAdsCallbackAdFn fn, void* userData, InMobiAd* ad)

Method Description

This API is used to register various callbacks of the banner ad view.

Parameter Descriptions

cbid: (InMobiAdsCallbackAd) Callback ID
fn: (InMobiAdsCallbackAdFn) fn name, which handles the corresponding callback
userData: (void *) Data passed as parameter can be retrieved back in the callback function.
ad: (InMobiAd*) ID of the banner ad for which developer wants to register callback

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

For example, if you want to register INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED

Use it as follows:

InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, int_request_completed, NULL);
static int int_request_completed(void *systemData, void *userData)
{
// Write code to handle callback
}

Note systemData is error description string in case of INMOBIADS_CALLBACK_AD_REQUEST_FAILED callback and is “NULL” in all other cases.

Method Signature

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

Method Description

This API is used to de-register various callbacks of the banner ad view

Parameter Descriptions

cbid: (InMobiAdsCallbackAd) Callback Id
fn: (InMobiAdsCallbackAdFn) fn name, which handles the corresponding callback
ad: (InMobiAd*) ID of the banner ad for which developer wants to de-register callback

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

If you want to de-register INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED , the method can be used as follows:

InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED, ad_request_completed, ad_id);

Method Signature

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

Method Description

This API is used to register various callbacks of the interstitial ad view.

Parameter Descriptions

cbid: (InMobiAdsCallbackAd) Callback Id
fn: (InMobiAdsCallbackAdFn) fn name, which handles the corresponding callback
userData: (void *) Data passed as parameter can be retrieved back in the callback function

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

For example, if you want to register INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED

Use it as follows:

InMobiAdsRegisterAdCallback(INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED, ad_request_completed, NULL, ad_id);
static int ad_request_completed(InMobiAd* ad, void *systemData, void *userData)
{
// Write code to handle callback
}

Note: systemData is error description string in case of INMOBIADS_CALLBACK_INT_REQUEST_FAILED callback and is “NULL” in all other cases.

Method Signature

s3eResult InMobiAdsUnRegisterIntCallback(InMobiAdsCallbackInt cbid, InMobiAdsCallbackIntFn fn)

Method Description

This API is used to de-register various callbacks of the ad view.

Parameter Descriptions

cbid: (InMobiAdsCallbackAd) Callback Id
fn: (InMobiAdsCallbackAdFn) fn name, which handles the corresponding callback.

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

For example, if you want to de-register INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED

Use it as follows:

InMobiAdsUnRegisterAdCallback(INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED, int_request_completed);

CallBacks for Banner Ads

  • INMOBIADS_CALLBACK_AD_REQUEST_COMPLETED - Sent when a banner ad request loaded an ad successfully.
  • INMOBIADS_CALLBACK_AD_REQUEST_FAILED - Sent when a banner ad request failed to load. Also error description string is retrieved in the (void *) systemData variable.
  • INMOBIADS_CALLBACK_AD_SHOW_SCREEN - Sent when the banner ad view presents a full screen view to the user.
  • INMOBIADS_CALLBACK_AD_DISMISS_SCREEN - Sent when the banner ad view dismisses the full screen view.
  • INMOBIADS_CALLBACK_AD_LEAVE_APPLICATION - Sent just before the application goes into the background, or terminates, because the user clicked on a banner ad that will launch another application (such as the App Store).
  • INMOBIADS_CALLBACK_AD_INTERACTED - Sent when the user interacts with the banner ad.

CallBacks for Interstitial Ads

  • INMOBIADS_CALLBACK_INT_REQUEST_COMPLETED - Sent when an interstitial ad request loaded an ad successfully.
  • INMOBIADS_CALLBACK_INT_REQUEST_FAILED - Sent when an interstitial ad request failed to load. Also error description string is retrieved in the (void *) systemData variable
  • INMOBIADS_CALLBACK_INT_SHOW_SCREEN - Sent when the interstitial adview is presented to the user.
  • INMOBIADS_CALLBACK_INT_DISMISS_SCREEN - Sent when the interstitial adview is dismissed.
  • INMOBIADS_CALLBACK_INT_LEAVE_APPLICATION - Sent just before the application goes into the background, or terminates, because the user clicked on an interstitial ad that will launch another application (such as the App Store)
  • INMOBIADS_CALLBACK_INT_INTERACTED - Sent when the user interacts with the interstitial ad.

Inmobi Analytics

InMobi extension also brings you to the Inmobi Analytics.

There are ten analytics methods that you can use to track the user behaviour.

Methods for Integrating Analytics

Method Signature

s3eResult analytics_startSessionManually()>/code>

Method Description

This API is used to initialize the session when the application is started.

  1. No parameters are required

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage Example

analytics_startSessionManually();

Method Signature

s3eResult analytics_startSessionManually_withParams(const char* params)

Method Description (Android ONLY)

This API is used to initialize the session with parameters during application start up time.

Parameter Descriptions

1. params : (const char*) value of param is a key-value pair

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

const char* sessionKeyValue = “key1:value1,key2:value”;<br /> analytics_startSessionManually_withParams(sessionKeyValue)

Method Signature

s3eResult analytics_endSessionManually();

Method Description

This API is used to close the session during application stop time.

Parameter Descriptions

1. No parameters are required

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage Example

s3eResult analytics_endSessionManually();

Method Signature

s3eResult analytics_endSessionManually_withParams(const char* params)

Method Description (Android ONLY)

This API is used to initialize to end the session with parameters during application stop time.

Parameter Descriptions

params : (const char*) The value of param is a key-value pair.

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage Example

const char* sessionKeyValue = “session1:value1,session2:value” ;<br /> analytics_endSessionManually_withParams(sessionKeyValue);

Method Signature

s3eResult analytics_beginSection(const char* sectionName)

Method Description
This API is used to create a section in the app for tracking different events.

Parameter Descriptions
1. sectionName: (const char*) value is a Section name

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

const char* sectionName = “level1game”;<br /> s3eResult analytics_beginSection(sectionName);<br />

Method Signature

s3eResult s3eResult analytics_endSection_withParams(const char* sectionName,const char* params)<br /> <br />

Method Description

This API is used to initialize the start section with parameters and section name

Parameter Descriptions

1. sectionName: (const char*) This value is a Section name
2. params : (const char*) This value of param is a key-value pair.

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

const char* sectionName = “level1game”;

analytics_endSectionManually_withParams(sectionName,sectionKeyValue);

Method Signature

s3eResult analytics_tagEvent(const char* tagEventName)

Method Description

This API is used to create a custom event in the app using tag name.

Parameter Descriptions

tagEventName:(const char*) This value is a tag event name.

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

const char* tagEventName = “earnedpoints”;

s3eResult analytics_tagEvent(tagEventName);

Method Signature

s3eResult s3eResult analytics_tagEvent_withParams(const char* tagEventName ,const char* params)

Method Description

This API is used to create the custom event with parameters

Parameter Descriptions

1. tagEventName: (const char*) This value is a tag event name.

2. params : (const char*) This value of param is a key-value pair.

Return Value

S3E_RESULT_SUCCESS

The operation completed successfully.

S3E_RESULT_ERROR

An error occurred during the operation.

Usage example

const char* tagEventName = “earnedpoints”;

const char* tagEventKeyValue = “event1:value1,event2:value” ;

analytics_tagEvent_withParams(tagEventName,tagEventKeyValue);

On This Page

Last Updated on: 28 Aug, 2015