This component suite provides components, which present banners and interstitials. They can be used for cross promotions and in-house ads or they can be used as a basis for paid ads services.
For banner paid ads, see TJVEAdMob and TJVEFacebookBanner controls, which subclasses from TJVEBanners and uses its capabilities as a fallback mechanism, when ads are not available.
For a better way to present paid interstitials, see Interstitials Use Case section below.
Presenting Interstitials
File: JVE.Interstitials.pas Inheritance: TComponent ⬅ TJVEInterstitials
This control presents interstitials (ads and promos) on major events. For example, finishing a level is a major event in your game; you can use this component to show ads / promos when the user finishes a level. The properties exposed by this component are:
- Interstitials – the list of interstitials to show. See List of Ads / Cross Promos section below for details.
- EachTimeToAd – time (in seconds) to pass from the moment the application is started, until the interstitial is presented the first time.
- FirstTimeToAd – time to pass from the moment the application is started for the very first time, until the interstitial is presented the first time. It is generally advisable to limit the number of ads the user sees the very first time the app is opened.
- TimeBetweenAds – time to pass between interstitials presentations.
- EventPenalty – if events occur more often than usual, you can specify the penalty time (in seconds) for each major event.
This component does not expose any events and just one function: ProcessMajorEvent. Use this function to mark the major event within the app. This function is the one, which could show the interstitial (if appropriate).
It will return True, if the interstitial was (and thus, is being) presented (the function returns immediately).
Since clicking the interstitial might take the user out of the app and it is not known when (if) he will be back, if this function returns True, make sure the app is idle (waiting for user input) and its state is saved.
An interstitial is presented on major events (calls to the ProcessMajorEvent function), but not before a specified time has passed.
You can specify a given time between ads (or 0, in case every major event deserves an ad). You can also specify a time penalty for major events, so you can specify:
- Time Between Ads – 60 seconds
- Major Event Penalty – 20 seconds
A usual user will see an ad every 60 seconds or more, but a user, which opens a level and closes it immediately will see an ad sooner: maybe after just 20 seconds, if in that time he managed to open and close levels 3 times.
In addition to the above functionality, this component also exposes one class procedure: ShowInterstitial(Bitmap, ClickCallback, CloseCallback). This procedure is provided as a convenience. It presents an interstitial and calls the call back procedure, if the user clicked the interstitial.
The presentation of the interstitials generally looks the same on all platforms:
Presenting Banners
File: JVE.Banners.pas Inheritance: TControl ⬅ TJVEBanners
This control presents an ad-banner like control, which cycles through the defined banners. The best placement for the banners control is aligned to the bottom of the application window. The following properties are exposed by this control:
- Banners – the list of banners to show. See List of Ads / Cross Promos section below for details.
- BannerTimeout – the time (in seconds) each banner is displayed, before the control switches to the next available banner.
In addition to these, a single event is provided by this control: OnHasAdsChanged. This event is called when a banner becomes available or when no banners are now available (a read/only HasAds property is also available, returning the current control state).
You can use this event to hide the control and reclaim its space in the circumstances when you might be in a situation where you no longer have any ads, which might be presented.
This control can be used as a fallback for actual paid ads service. You can use a ready TJVEAdMob control for that or, if you prefer another ad network, see TJVEAdMob for an example implementation of this sort.
The banners are presented as images stretched (but preserving aspect ratio) on the black background. Here is MS Windows presentation example:
List of Ads / Cross Promos
Both, TJVEInterstitials and TJVEBanners use a collection of TJVEActions to hold the banners / interstitials, which can be included in the ads rotation.
The following properties are exposed by these collection items (no functions are exposed by them):
- Action – specifies the action, to be taken if the ad is clicked. This should be a component implementing IJVEExecutable or IJVEInterstitial See below for details.
- Weight – the relative frequency, this ad should be shown, relative to other ads.
- Bitmap – the banner bitmap that should be presented for this ad. Only exposed for IJVEExecutable. Only present for backward compatibility and/or interstitial-only actions. See AppDetails
- Identifier – the identifier, which should be paid for (only for TJVEPayment).
- AppDetails – exposes the ad details: title, description, advertiser, rating, icon, banner (the legacy Bitmap property) and call to action to use. It also includes URL (click target) and list of beacons (URL to call when the ad is presented). Only exposed for IJVEExecutable.
The TJVEAction items have design-time editors, which show and hide properties, based on the Action selection. So, based on your selection you might see any of the following:
A design-time editor is provided for the Action property itself: it will only list components, implementing those two interfaces. If you assign an invalid component to the Action property in runtime, that action will be skipped from the rotation.
The Identifier property will allow you to select one of the payment item identifiers, defined within the selected TJVEPayment. Again, if invalid identifier is selected indirectly, the action will be excluded from the rotation.
IJVEInterstitial entities provide their own user interface, so there is no Bitmap property for them and they cannot be selected for rotation in the TJVEBanners control.
If Bitmap or AppDetails property is in effect, you can also provide OnLoad and OnUnload events, which could be used to load and unload the bitmaps on demand to preserve memory (especially important on mobile devices).
The actions will be automatically excluded from rotation, if they are not currently valid: IJVEInterstitial will be excluded if it is not yet cached; IJVEExecutable will be excluded if it cannot be opened (for example if a persistent payment was already made or if a cross-promoted app is already installed and the ExistsAction is set to ignore).
Custom Ads
You can create your own implementations of IJVEInterstitial (see TJVEChartBoost for a convenient example) or of IJVEExecutable (see TJVEOpenURL for a convenient example). If you don’t want to subclass, a basic implementation of IJVEExecutable is provided as part of this suite:
File: JVE.Interstitials.pas Inheritance: TComponent ⬅ TJVECustomAd
This component does not expose any properties or methods at all, but it exposes two events, which are defined as follows:
- OnClick – occurs when the user clicks on the presented ad.
- OnShouldOpen – occurs just before the final decision to present this ad is taken. Return False value in the Show parameter, if you don’t want this ad to be presented now (for any reason). If you don’t provide this event, the ad is always considered to be valid.
If you need to update the bitmap and any other aspect of the ad, which will be presented to the user, you can also do that within the OnShouldOpen event (it is directly accessible there as Item.Bitmap or Item.AppDetails).
Interstitials Use Case
Here is the way, to define the Interstitials collection of the TJVEInterstitials component, if you want to present Chartboost and RevMob ads (giving priority to Chartboost), have a fallback to cross-promo of your other two apps and have an app rating reminder:
