From 6ba1d4908b36d644a1de2b3bd677842ab4cb6241 Mon Sep 17 00:00:00 2001 From: Ibby Date: Tue, 6 Dec 2016 08:29:39 -0500 Subject: [PATCH] feat(admob): update api and docs --- src/plugins/admob.ts | 224 +++++++++++++++++++++++++++++-------------- 1 file changed, 152 insertions(+), 72 deletions(-) diff --git a/src/plugins/admob.ts b/src/plugins/admob.ts index d806519b71..a1233baf49 100644 --- a/src/plugins/admob.ts +++ b/src/plugins/admob.ts @@ -1,25 +1,106 @@ import { Cordova, Plugin } from './plugin'; import { Observable } from 'rxjs/Observable'; +export type AdMobAdSize = 'SMART_BANNER' | 'BANNER' | 'MEDIUM_RECTANGLE' | 'FULL_BANNER' | 'LEADERBOARD' | 'SKYSCRAPER' | 'CUSTOM'; + +export interface AdMobOptions { + + /** + * Banner Ad Size, defaults to `SMART_BANNER`. IT can be: `SMART_BANNER`, `BANNER`, `MEDIUM_RECTANGLE`, `FULL_BANNER`, `LEADERBOARD`, `SKYSCRAPER`, or `CUSTOM` + */ + adSize?: AdMobAdSize; + + /** + * Banner width, valid when `adSize` is set to `CUSTOM` + */ + width?: number; + + /** + * Banner height, valid when `adSize` is set to `CUSTOM` + */ + height?: number; + + /** + * Allow banner to overlap webview, or else it will push webview up or down to avoid overlap. Defaults to false. + */ + overlap?: boolean; + + /** + * Position of banner ad. Defaults to `TOP_CENTER`. You can use the `AdMob.AD_POSITION` property to select other values. + */ + position?: number; + + /** + * X in pixels. Valid when `position` is set to `POS_XY` + */ + x?: number; + + /** + * Y in pixels. Valid when `position` is set to `POS_XY` + */ + y?: number; + + /** + * Set to true to receive test ad for testing purposes + */ + isTesting?: boolean; + + /** + * Auto show interstitial ad when loaded. Set to false if hope to control the show timing with prepareInterstitial/showInterstitial + */ + autoShow?: boolean; + + /** + * Re-create the banner on web view orientation change (not screen orientation), or else just move the banner. Default:true. + */ + orientationRenew?: boolean; + + /** + * Set extra color style for Ad + */ + adExtras?: AdMobAdExtras; + +} + +export interface AdMobAdExtras { + + color_bg: string; + + color_bg_top: string; + + color_border: string; + + color_link: string; + + color_text: string; + + color_url: string; + +} + /** * @name AdMob - * @description Plugin for Google Ads, including AdMob / DFP (doubleclick for publisher) and mediations to other Ad networks. + * @description + * Plugin for Google Ads, including AdMob / DFP (doubleclick for publisher) and mediations to other Ad networks. * @usage * ```typescript * import { AdMob } from 'ionic-native'; * * ionViewDidLoad() { - * AdMob.onBannerDismiss() - * .subscribe(() => { console.log('User returned from interstitial'); }); + * AdMob.onAdDismiss() + * .subscribe(() => { console.log('User dismissed ad'); }); * } * - * public onClick() { + * onClick() { * AdMob.prepareInterstitial('YOUR_ADID') * .then(() => { AdMob.showInterstitial(); }); * } * * ``` - * Please refer the the plugin's original repository for detailed usage. + * + * @interfaces + * AdMobOptions + * AdMobAdExtras */ @Plugin({ pluginName: 'AdMob', @@ -31,15 +112,32 @@ import { Observable } from 'rxjs/Observable'; export class AdMob { /** - * - * @param adIdOrOptions + * @private + */ + static AD_POSITION = { + NO_CHANGE: 0, + TOP_LEFT: 1, + TOP_CENTER: 2, + TOP_RIGHT: 3, + LEFT: 4, + CENTER: 5, + RIGHT: 6, + BOTTOM_LEFT: 7, + BOTTOM_CENTER: 8, + BOTTOM_RIGHT: 9, + POS_XY: 10 + }; + + /** + * Create a banner + * @param adIdOrOptions {string | AdMobOptions} Ad ID or Options * @returns {Promise} Returns a Promise that resolves when the banner is created */ @Cordova() - static createBanner(adIdOrOptions: any): Promise { return; } + static createBanner(adIdOrOptions: string | AdMobOptions): Promise { return; } /** - * + * Destroy the banner, remove it from screen. */ @Cordova({ sync: true @@ -47,18 +145,18 @@ export class AdMob { static removeBanner(): void { } /** - * - * @param position + * Show banner at position + * @param position {number} Position. Use `AdMob.AD_POSITION` to set values. */ @Cordova({ sync: true }) - static showBanner(position: any): void { } + static showBanner(position: number): void { } /** - * - * @param x - * @param y + * Show banner at custom position + * @param x {number} Offset from screen left. + * @param y {number} Offset from screen top. */ @Cordova({ sync: true @@ -66,7 +164,7 @@ export class AdMob { static showBannerAtXY(x: number, y: number): void { } /** - * + * Hide the banner, remove it from screen, but can show it later */ @Cordova({ sync: true @@ -74,35 +172,28 @@ export class AdMob { static hideBanner(): void { } /** - * - * @param adIdOrOptions + * Prepare interstitial banner + * @param adIdOrOptions {string | AdMobOptions} Ad ID or Options * @returns {Promise} Returns a Promise that resolves when interstitial is prepared */ @Cordova() - static prepareInterstitial(adIdOrOptions: any): Promise { return; } + static prepareInterstitial(adIdOrOptions: string | AdMobOptions): Promise { return; } /** - * Show interstitial + * Show interstitial ad when it's ready */ @Cordova({ sync: true }) static showInterstitial(): void { } - /** - * - * @returns {Promise} Returns a Promise that resolves when the interstitial is ready - */ - @Cordova() - static isInterstitialReady(): Promise { return; } - /** * Prepare a reward video ad - * @param adIdOrOptions + * @param adIdOrOptions {string | AdMobOptions} Ad ID or Options * @returns {Promise} Returns a Promise that resolves when the ad is prepared */ @Cordova() - static prepareRewardVideoAd(adIdOrOptions: any): Promise { return; } + static prepareRewardVideoAd(adIdOrOptions: string | AdMobOptions): Promise { return; } /** * Show a reward video ad @@ -114,11 +205,11 @@ export class AdMob { /** * Sets the values for configuration and targeting - * @param options Returns a promise that resolves if the options are set successfully + * @param options {AdMobOptions} Options * @returns {Promise} Returns a Promise that resolves when the options have been set */ @Cordova() - static setOptions(options: any): Promise { return; } + static setOptions(options: AdMobOptions): Promise { return; } /** * Get user ad settings @@ -127,65 +218,54 @@ export class AdMob { @Cordova() static getAdSettings(): Promise { return; } + /** + * Triggered when failed to receive Ad + * @returns {Observable} + */ @Cordova({ eventObservable: true, - event: 'onBannerFailedToReceive' - }) - static onBannerFailedToReceive(): Observable { return; } - - @Cordova({ - eventObservable: true, - event: 'onBannerReceive' - }) - static onBannerReceive(): Observable { return; } - - @Cordova({ - eventObservable: true, - event: 'onBannerPresent' - }) - static onBannerPresent(): Observable { return; } - - @Cordova({ - eventObservable: true, - event: 'onBannerLeaveApp' - }) - static onBannerLeaveApp(): Observable { return; } - - @Cordova({ - eventObservable: true, - event: 'onBannerDismiss' - }) - static onBannerDismiss(): Observable { return; } - - @Cordova({ - eventObservable: true, - event: 'onInterstitialFailedToReceive' + event: 'onAdFailLoad' }) - static onInterstitialFailedToReceive(): Observable { return; } + static onAdFailLoad(): Observable { return; } + /** + * Triggered when Ad received + * @returns {Observable} + */ @Cordova({ eventObservable: true, - event: 'onInterstitialReceive' + event: 'onAdLoaded' }) - static onInterstitialReceive(): Observable { return; } - + static onAdLoaded(): Observable { return; } + /** + * Triggered when Ad will be showed on screen + * @returns {Observable} + */ @Cordova({ eventObservable: true, - event: 'onInterstitialPresent' + event: 'onAdPresent' }) - static onInterstitialPresent(): Observable { return; } + static onAdPresent(): Observable { return; } + /** + * Triggered when user click the Ad, and will jump out of your App + * @returns {Observable} + */ @Cordova({ eventObservable: true, - event: 'onInterstitialLeaveApp' + event: 'onAdLeaveApp' }) - static onInterstitialLeaveApp(): Observable { return; } + static onAdLeaveApp(): Observable { return; } + /** + * Triggered when dismiss the Ad and back to your App + * @returns {Observable} + */ @Cordova({ eventObservable: true, - event: 'onInterstitialDismiss' + event: 'onAdDismiss' }) - static onInterstitialDismiss(): Observable { return; } + static onAdDismiss(): Observable { return; } }