Integration Guides


Appcelerator Titanium - version 9.2.1

Full Guide

Getting Started

Ad Unit

Advanced

SDK Package

1 Configuration

  1. Add your app to our system and get your App ID.
  2. Download the .zip file with the latest version our module.
  3. Add the Revmob Modules for Android and iOS platforms in the Appcelerator Titanium folder, according to your operating system.
  4. In your project, in the tiapp.xml file, add both modules, or the one you are building for. See the image below for reference.
  5. Also in your tiapp.xml, add the required internet permission.
  6. For more details on how to include a module in Appcelerator Titanium, click here.
ant_smasher_fullscreen

Adding Revmob's modules to your project

2 Start Session

Before showing any ads, you must initialize our SDK. It's a best practice to do it as soon as your app is ready, so you can call ads easily whenever you want to.

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
//Fired when session has been completely started
});
revmob.addEventListener('onRevMobSessionNotStarted', function(e) {
//Fired when session has not been completely started
Titanium.API.log(e);
});
$.index.open();
            

Revmob ads will only work if Revmob's session was started.

3 Testing

While you're developing your app, you will only receive test ads. Your app must make at least one ad request while on test mode in order to be validated before receiving live ads. Be sure you are able to receive at least one of our sample ads and that it’s redirecting to our "Success Page" when clicked. Once you are able to receive our sample ads it means you’ve successfully integrated our sdk.

sample_ads

Fullscreen sample, Banner sample, and Success Page

4 Go Live

Once you're finished and your app is in the store with our SDK, click on the "Go live" button in your Apps page and insert your app's URL. It may take up to 48h for your app to be approved. After that, it will start receiving live ads.

app_store_idfa

5 Kids Category

Apps designed for families have special regulations for monetizing. As stated in Google Play's guidelines and in Apple's guidelines, they may not include behavioral advertising and the ads must be appropriate for kids.
Revmob is fully COPPA compliant. To specify that your app is designed for kids and to guarantee that it's fully compliant, you must set the user minimum age when your user is 13 or less years old:

revmob.setUserAge(10);
            

You also can not display a fullscreen ad immediately upon app launch nor show more than one ad placement per page.

Attention:
This method is only to protect children from abusive advertising. Setting the user age incorrectly may affect your eCPM due to our algorithms using this information for retargeting.

6 Upload to App Store

When uploading your app to App Store with Revmob SDK, you will be asked about the use of IDFA.
Revmob uses IDFA for targeting purposes. Check "Yes" on the option at the right side of the page, as it will improve your earnings a lot.
Then, on the last three checkboxes:

  1. Check this box to serve ads.
  2. Check this box if you are also advertising the app you are uploading, and its installations will be tracked.
  3. This check is optional, as it's not used by Revmob.
app_store_idfa

1 Native Button/Link

You have full control over this ad unit's layout. You design it, attach our method to its click event and the user will be redirected to the Play Store.
A common usage is to associate it to a "more games" button or to a custom banner your team designed.
Keep in mind that the image associated with this link must be clearly identified as an advertising.

Implementation

The best implementation is to pre-cache the ad and only display the button when receiving an event callback from the Revmob module:

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
    var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
    var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
    revmob.createLink();
});
revmob.addEventListener('onRevMobLinkReceived', function(e) {
    revmob.openLink();
});
$.index.open();
            

You can also only call the openLink() method when clicked:

revmob.openLink();
    // This code redirects the user to the store, so you should trigger it when your button is clicked
            

You can learn more about RevMobAdsEvent in the Event Listener section.

Reminder:
Before calling any of our ads, you must start a Revmob session, otherwise, ads won't be shown.
See here how to start a Revmob session.

ant_smasher_native

100-million-downloads Ant Smasher's success case.

2 Fullscreen

The Interstitial is an advertisement that fills the whole screen. It's usually shown:

  1. On app start;
  2. Before/after a game round;
  3. After a service is used (e.g. alarm turned off).

When pre-caching, the ad received can either be a static interstitial or a video ad. Our servers will always return the one that can pay you more.

Implementation

You should pre-cache the ad before showing it with thecreateFullscreen() and showLoadedFullscreen() methods.

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
    var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
    var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
    revmob.createFullscreen();
});
revmob.addEventListener('onRevMobFullscreenReceived', function(e) {
    revmob.showLoadedFullscreen();
});
$.index.open();
            

You can also only call the basicUsageFullscreen() method when clicked:

revmob.basicUsageFullscreen();
    // This code will load the ad and display it on screen as soon as it completes loading
            

Using this method can affect the UX as the loading of the ad may take a long time due to the user's net speed.
That's why we recommend you pre-cache your ads and serve them after receiving the event that the ad was completely loaded, as it will improve UX.
You can learn more about the events fired in the Event Listener section.

Reminder
Before calling any of our ads, you must start a Revmob session, otherwise, ads won't be shown.
Check here how to start a Revmob session.

ant_smasher_fullscreen

Revmob's Fullscreen test ad.

3 Banner

Banner ad is a View with the standard size of 320x50 for phones and 728x90 for tablets, though you can customize it for your app.
You can use it in 2 different ways:

  • Basic Banner
  • Custom Banner

Basic Banner

This method is the simplest way to show a banner ad.
The banner will be displayed at the bottom of the screen, with its specific width.
You should pre-cache the ad before showing it using the loadBanner() and showBanner() methods:

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
    var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
    var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
    revmob.loadBanner();
});
revmob.addEventListener('onRevMobBannerReceived', function(e) {
    Titanium.API.log('[RevMob Titanium Sample App] Banner received');
    revmob.showBanner();
});
$.index.open();
            

To hide the basic banner, just write the code below:

revmob.hideBanner();
            

If you hide the ad, you can call showBanner() to show the same add. To request a new banner, you have to release the old ad and then call loadBanner() again.

revmob.releaseBanner();
            

Custom Banner

You can display a banner with custom positioning and size. The origin will always be the top left corner of the screen.
You should pass 4 Int value parameters to the load and show methods:
loadCustomBanner(leftMargin, topMargin, bannerWidth, bannerHeight)
showCustomBanner(leftMargin, topMargin, bannerWidth, bannerHeight)

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
    var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
    var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
    revmob.loadCustomBanner(0, 200, 320, 50);
});
revmob.addEventListener('onRevMobCustomBannerReceived', function(e) {
    Titanium.API.log('[RevMob Titanium Sample App] Custom banner received');
    revmob.showCustomBanner(0, 200, 320, 50);
});
$.index.open();
            

To hide the custom banner, just write the code below:

revmob.hideCustomBanner();
            

If you hide the ad, you can call showBanner() to show the same add. To request a new banner, you have to release the old ad and then call loadBanner() again.

revmob.releaseCustomBanner();
            

Reminder:
Before calling any of our ads, you must start a Revmob session, otherwise, ads won't be shown.
See here how to start a Revmob session.

ant_smasher_banner

100-million-downloads Ant Smasher's home menu banner.

4 Video

To show a video ad, you must call the createVideo method. A good place to call this method is after the startSession.
Then, when you receive a callback from our onRevMobVideoLoaded listener, you can call the showVideo method. A good place to call this method is after a game over, for example.

Basic Usage

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
    var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
    var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
    revmob.createVideo();
});
revmob.addEventListener('onRevMobVideoLoaded', function(e) {
    revmob.showVideo();
});
$.index.open();
            

Listener Usage

These are the Revmob Events fired when video methods are called:

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
    var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
    var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
    //Fired when session has completely started
    revmob.createVideo();
});
revmob.addEventListener('onRevMobSessionNotStarted', function(e) {
    //Fired when session has not completely started
    Titanium.API.log(e);
});
//Video Listeners
revmob.addEventListener('onRevMobVideoLoaded', function(e) {
    //Fired when the video is completely loaded
    //You can show the video after this listener is fired.
    revmob.showVideo();
});
revmob.addEventListener('onRevMobVideoNotReceived', function(e) {
    //Fired when there is a problem downloading the video
    //You can log the error to see more details.
    Titanium.API.log(e);
});
revmob.addEventListener('onRevMobVideoStarted', function(e) {
    //Fired when the video has started playing
});
revmob.addEventListener('onRevMobVideoClicked', function(e) {
    //Fired when the video is clicked
});
revmob.addEventListener('onRevMobVideoDismiss', function(e) {
    //Fired when the video is dismissed
});
revmob.addEventListener('onRevMobVideoNotPreloaded', function(e) {
    //Fired when you try to show a videoAd without pre-caching it first
    //or if you try to show it before the "onRevMobVideoLoaded" event is fired
});
$.index.open();
            
ant_smasher_video

Revmob's Video test ad

5 Rewarded Video

The most common way to display Rewarded Videos is by disclaiming that a video will be shown, and that the user will earn something for watching the ad. To use Revmob Rewarded Video Ads, you must pre-cache them before they're displayed. To pre-cache, call the createRewardedVideo() method and to display the ad, call the showRewardedVideo() method.

Basic Usage

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
    var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
    var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
    revmob.createRewardedVideo();
});
revmob.addEventListener('onRevMobRewardedVideoLoaded', function(e) {
    revmob.showRewardedVideo();
});
$.index.open();
            

Listeners Usage

These are all the Revmob Events fired when rewarded video methods are called:

var moduleNames = { 'iPhone OS': 'com.revmob.titanium',  'android': 'com.revmob.ti.android' };
var revmob = require(moduleNames[Ti.Platform.name]);
if (Ti.Platform.osname === 'android') {
    var appId = "<YOUR_APP_ID_ANDROID>";
}else if (Ti.Platform.osname === 'iphone') {
    var appId = "<YOUR_APP_ID_IOS>";
}
revmob.startSession(appId);
revmob.addEventListener('onRevMobSessionStarted', function(e) {
        //Fired when session has completely started
        revmob.createRewardedVideo();
});
revmob.addEventListener('onRevMobSessionNotStarted', function(e) {
        //Fired when session has not completely started
        Titanium.API.log(e);
});
//Rewarded video Listeners
revmob.addEventListener('onRevMobRewardedVideoLoaded', function(e) {
        //Fired when the rewarded video is completely loaded
        //You can show the rewarded video after this listener is fired
});
        revmob.showRewardedVideo();
revmob.addEventListener('onRevMobRewardedVideoNotReceived', function(e) {
        //Fired when there is a problem downloading the rewarded video
        //You can log the error to see more details
        Titanium.API.log(e);
});
revmob.addEventListener('onRevMobRewardedVideoStarted', function(e) {
        //Fired when the rewarded video has started playing
});
revmob.addEventListener('onRevMobRewardedVideoCompleted', function(e) {
        //Fired when the rewarded video finished playing and the user can have his/her reward
});
revmob.addEventListener('onRevMobRewardedVideoNotPreloaded', function(e) {
        //Fired when you try to show a rewarded video without pre-caching it first
        //or if you try to show it before the "onRevMobRewardedVideoLoaded" event is fired
});
$.index.open();
            
ant_smasher_video

Revmob's video test ad

1 Event Listeners

With Listeners (also known as Delegates or Callbacks) you can follow the ad workflow. The Revmob SDK will fire events for every important change in the ad state. For example, you can identify if the ad was loaded successfully or if the user clicked on the ad.
Register the events you want to listen for in your initialization function. The event listener function will call your custom function when the desired event is triggered in the SDK.

Start Session

revmob.addEventListener('onRevMobSessionStarted', function(e) { } );
revmob.addEventListener('onRevMobSessionNotStarted', function(e) { });
            

Basic Usage Fullscreen

revmob.addEventListener('onRevMobBasicUsageFullscreenDismissed', function(e) { });
revmob.addEventListener('onRevMobBasicUsageFullscreenClicked', function(e) { });
revmob.addEventListener('onRevMobBasicUsageFullscreenNotReceived', function(e) { });
revmob.addEventListener('onRevMobBasicUsageFullscreenDisplayed', function(e) { });
revmob.addEventListener('onRevMobBasicUsageFullscreenReceived', function(e) { });
            

Fullscreen

revmob.addEventListener('onRevMobFullscreenReceived', function(e) { });
revmob.addEventListener('onRevMobFullscreenNotReceived', function(e) { });
revmob.addEventListener('onRevMobFullscreenDisplayed', function(e) { });
revmob.addEventListener('onRevMobFullscreenDismissed', function(e) { });
revmob.addEventListener('onRevMobFullscreenClicked', function(e) { });
revmob.addEventListener('onRevMobFullscreenNotPreloaded', function(e) { });
            

Banner

revmob.addEventListener('onRevMobBannerReceived', function(e) { });
revmob.addEventListener('onRevMobBannerNotReceived', function(e) { });
revmob.addEventListener('onRevMobBannerDisplayed', function(e) { });
revmob.addEventListener('onRevMobBannerDismissed', function(e) { });
revmob.addEventListener('onRevMobBannerClicked', function(e) { });
            

Custom Banner

revmob.addEventListener('onRevMobCustomBannerReceived', function(e) { });
revmob.addEventListener('onRevMobCustomBannerNotReceived', function(e) { });
revmob.addEventListener('onRevMobCustomBannerDisplayed', function(e) { });
revmob.addEventListener('onRevMobCustomBannerDismissed', function(e) { });
revmob.addEventListener('onRevMobCustomBannerClicked', function(e) { });
            

Native Button/Link

revmob.addEventListener('onRevMobLinkReceived', function(e) { });
revmob.addEventListener('onRevMobLinkClicked', function(e) { });
revmob.addEventListener('onRevMobLinkNotReceived', function(e) { });
            

Video

revmob.addEventListener('onRevMobVideoLoaded', function(e) { });
revmob.addEventListener('onRevMobVideoNotReceived', function(e) { });
revmob.addEventListener('onRevMobVideoStarted', function(e) { });
revmob.addEventListener('onRevMobVideoClicked', function(e) { });
revmob.addEventListener('onRevMobVideoDismissed', function(e) { });
revmob.addEventListener('onRevMobVideoNotPreloaded', function(e) { });
            

Rewarded Video

revmob.addEventListener('onRevMobRewardedVideoLoaded', function(e) { });
revmob.addEventListener('onRevMobRewardedVideoNotReceived', function(e) { });
revmob.addEventListener('onRevMobRewardedVideoStarted', function(e) { });
revmob.addEventListener('onRevMobRewardedVideoCompleted', function(e) { });
revmob.addEventListener('onRevMobRewardedVideoNotPreloaded', function(e) { });
            

1 Change Log (yyyy/mm/dd)

9.2.1 (2016/09/08)

  • ImportantUpdate Improved Android banner pre caching

9.2.0 (2016/08/11)

  • ImportantBugfixImproved memory performance.
  • NewAdded Load and Release Banner.
  • UpdateImproved Video Ad UX.
  • BugfixFixed minor bugs.

9.1.0 (2016/07/10)

  • NewImportantBugfix Passed through new extensive Quality Assurance procedures.
  • NewImportant Updated all ad methods
  • New New listeners for each ad unit
  • Important Removed pop up ad

9.0.4 (2015/09/07)

  • New Added RevMob Button ad unit.
  • Bugfix Fixes an important issue affecting part of the clicks, lowering the eCPM.
  • Important Many internal improvements and performance enhances.

9.0.0 (2015/05/28)

  • New Added video ads, rewarded video ads and support to VAST.
  • New Refreshable banners.
  • Important Many internal improvements and performance enhances.

1.3.0 - 2015/04/07

  • Important Added x86_64 architecture support due to Apple's new requirement.
  • New Added refreshable banners.

1.2.4 - 2014/12/03

  • Important Internal improvements for iOS releases.

1.2.2 - 2014/11/28

  • Important Fixes violations in the newest Google's Policy for advertising
  • Important Fixes issues that were causing the SDK to be flagged by some antivirus

1.2.1 - 2014/09/09

  • NewImportant Support to iOS 8 and Android L.
  • NewImportant Added support to video ads.

1.2.0 - 2014/07/22

  • NewImportant Support for Google ID for Advertisement for Android (details).
  • NewImportant New listeners for Android for Eula popup window (details).
  • NewImportant New listeners for iOS and Android for start session (documentation).
  • ImportantBugfix Status bar was being shown even if the app was hiding it for iOS.
  • ImportantBugfix Fixed an issue that crashes the app if IDFV returns nil for iOS.
  • ImportantBugfix Banner was being shown in front of the keyboard for iOS.
  • ImportantBugfix Session could not be started if it failed in the first time for iOS.
  • ImportantBugfix Click listener for fullscreen was being called twice for Android.

1.1.5 - 2014/04/10

  • ImportantBugfix Fixes a bug on iOS that could lead to "SESSION NOT STARTED" warning.

1.1.4 - 2014/04/08

  • ImportantBugfix iOS banner was not hidding.

1.1.3 - 2014/03/13

  • UpdateImportant Fixes a bug on iOS that was preventing some apps to be approved at AppStore.
  • Bugfix iOS fullscreen and banner were not preserving app supported orientations.

1.1.2 - 2014/02/19

  • Update Internal improvements for Android releases.
  • Update Internal improvements for iOS releases.

1.1.1 - 2014/02/10

  • Bugfix Android listeners working properly now.

1.1.0 - 2013/11/18

  • new Basic banner for Android and iOS.
  • Update Internal improvements for Android releases.
  • Update Internal improvements for iOS releases.

1.0.0 - 2013/09/20

  • NewImportant Support to iOS 7 GM (arm64 architecture are not supported yet).
  • Important Dropped support to iOS 4.
  • Update Important internal improvements for Android releases.
  • Update Important internal improvements for iOS releases.

0.5.5 - 2013/08/26

  • New Fullscreen animations.
  • Delete Notification removed to respect the new Google policy.

0.5.4 - 2013/08/01

  • Update Important internal improvements for iOS releases.

0.5.3 (2013/07/25)

  • Update Important internal improvements for Android releases.
  • Update Important internal improvements for iOS releases.

0.5.2 (2013/07/19)

  • Update Sample app for Android and iOS.

0.5.1 (2013/07/08)

  • Update Important internal improvements.
  • Update Android notification ad requires user approval.
  • Update Support for Titanium 3.1.1.
  • Bugfix Fixed network bug in iOS.
  • Bugfix Fixed AdSupport configuration for iOS 5 and 7.

0.5.0 (2013/05/28)

  • Update Important internal improvements for Android releases.
  • Update Important internal improvements for iOS releases.
  • Optimization Using less memory in Android fullscreen.

0.4.1 (2013/04/09)

  • NewImportant iOS UDIDs are not collected anymore (More info).
  • Update Improvement on the logs.
  • Update Lots of internal improvements that will increase the eCPM significantly.
  • Update Android permissions validations (logs to alert implementation issues).
  • Bugfix Fixed an issue that can cause a click to fail on fullscreen.
  • Bugfix Fixed some issues that can prevent the notification of errors clicks.
  • Bugfix Fixed some issues that can cause memory leaks.

0.4.0 (2013/02/27)

  • Update Support to Titanium 3.0.2
  • Update Internal improvements on iOS and Android

0.3.0 (2013/02/14)

  • New Android: Pre-load of ad link.
  • New Android: Pre-load of popup.
  • New Android: Pre-load of fullscreen.
  • New Android: Notification ad.
  • New Android: Custom timeout.
  • New iOS: Custom timeout.
  • Update Improvements in the sample app.

0.2.0 (2012/12/27)

  • New Print environment information.

0.1.1 (2012/11/28)

  • Bugfix Fixed a bug tha could prevent to show ads on Android in some cases.
  • New Sample app now show how to use testing mode.
  • Bugfix Bug on the sample app xml.
  • Bugfix Solved bug with the sample app appIDs