Skip to content

中文文档

Jump to bottom
Phoenix Gao edited this page Apr 24, 2015 · 4 revisions

AdMob Plugin Pro 中文说明

用 Javascript 呈现 AdMob 广告赚钱，一行代码搞定 ！

亮点：

  • 支持广告条（Banner）和全屏广告（Interstitial）。
  • 多种广告条尺寸，甚至可以自定义尺寸。
  • 可以固定广告在屏幕顶端或底部，也可以悬浮模式。
  • 最灵活的广告呈现，可以在任意指定位置显示。
  • 横屏、竖屏，智能广告条自动适应。
  • 支持最新的 iOS SDK。
  • 支持最新的 Android Google play services。
  • 完全兼容 Intel XDK 和 Crosswalk。
  • 最简单的API，一行代码搞定广告显示。
  • 更新维护及时，技术支持到位。

友情提示：（根据最近 2 个月的数据统计）

  • 使用 AdMob Plugin Pro，比开源版本有更高的填充率（fill rate）。
  • 使用全屏广告，比广告条的收益更高，高达 5-10 倍。

名词：

  • 覆盖率（Fill rate）: 在你的App中广告显示的次数，除以广告请求的次数。
  • 收益率（RPM）: 显示 1000 次广告的收益。
  • Intel XDK: Intel 的 HTML5 移动应用开发环境和云服务，在云端构建打包，并且支持导入网上的第三方插件。
  • Adobe PhoneGap Build: Adobe的HTML5构建打包云服务，接受发布插件，但只允许使用经过审核批准的插件。

新闻：

  • 获得推荐：Telerik，发布在 Verified Plugins Marketplace. 更多 ...
  • 获得推荐：William SerGio，发表在 code project (20 Jun 2014), 更多 ...
  • 获得推荐：Arne，发表在 Scirra Game Dev Forum (07 Aug, 2014), 更多 ...
  • 获得推荐：Intel XDK团队 (08/22/2014), 更多 ...
  • 获得推荐：Scirra Construct 2 (09/12/2014)官方版本发布, read more ...

如何使用

如果使用 Cordova 命令行工具，按照如下步骤创建项目，添加插件：

cordova create <project_folder> com.<company_name>.<app_name> <AppName>
cd <project_folder>
cordova platform add android
cordova platform add ios

cordova plugin add com.google.cordova.admob

// copy the demo html file to www
rm -r www/*; cp plugins/com.google.cordova.admob/test/index.html www/

// connect device or run in emulator
cordova prepare; cordova run android; cordova run ios;

// or import into Xcode / eclipse

如果使用 Intel XDK，则按照如下步骤操作： Project -> CORDOVA 3.X HYBRID MOBILE APP SETTINGS -> PLUGINS AND PERMISSIONS -> Third-Party Plugins -> Add a Third-Party Plugin -> Get Plugin from the Web, input:

Name: AdMobPluginPro
Plugin ID: com.google.cordova.admob
[x] Plugin is located in the Apache Cordova Plugins Registry

快速上手的例子

步骤 1: 通过 AdMob 网站，创建相应的广告栏位 ID

var ad_units = {
	ios : {
		banner: 'ca-app-pub-6869992474017983/4806197152',
		interstitial: 'ca-app-pub-6869992474017983/7563979554'
	},
	android : {
		banner: 'ca-app-pub-6869992474017983/9375997553',
		interstitial: 'ca-app-pub-6869992474017983/1657046752'
	}
};
// 根据平台，自动选用相应的广告 ID
var admobid = ( /(android)/i.test(navigator.userAgent) ) ? ad_units.android : ad_units.ios;

步骤 2: 一行代码，显示广告条

// 显示广告条，默认在顶端的智能广告条
if(AdMob) AdMob.createBanner( admobid.banner );

// 或者, 在底部显示广告条
if(AdMob) AdMob.createBanner( {
	adId:admobid.banner, 
	position:AdMob.AD_POSITION.BOTTOM_CENTER, 
	autoShow:true} );

// 或者，已浮动模式，在底部显示方块广告
if(AdMob) AdMob.createBanner( {
	adId:admobid.banner, 
	adSize:'MEDIUM_RECTANGLE', 
	overlap:true, 
	position:AdMob.AD_POSITION.BOTTOM_CENTER, 
	autoShow:true} );

// 或者，在指定的位置，显示指定大小的广告
if(AdMob) AdMob.createBanner( {
	adId:admobid.banner, 
	adSize:'CUSTOM',  width:200, height:200, 
	overlap:true, 
	position:AdMob.AD_POSITION.POS_XY, x:100, y:200, 
	autoShow:true} );

步骤 3: 准备全屏广告，并在需要的时候显示

// 在后台准备广告资源，例如，在某个游戏关卡开始的时候
if(AdMob) AdMob.prepareInterstitial( {adId:admobid.interstitial, autoShow:false} );

// 显示全屏广告，例如，在某个游戏关卡结束的时候
if(AdMob) AdMob.showInterstitial();

完整的例子

参见源代码 [test/index.html] (https://github.com/floatinghotpot/cordova-admob-pro/blob/master/test/index.html).

API 概览

方法

javascript AdMob.setOptions(options);

AdMob.createBanner(adId/options, success, fail); AdMob.removeBanner(); AdMob.showBanner(position); AdMob.showBannerAtXY(x, y); AdMob.hideBanner();

AdMob.prepareInterstitial(adId/options, success, fail); AdMob.showInterstitialAd(); AdMob.isInterstitialReady(callback);


### 事件 ###
> **语法**: document.addEventListener(event_name, callback);

```javascript
// 以下事件，适用于广告条
'onBannerFailedToReceive'
'onBannerReceive'
'onBannerPresent'
'onBannerLeaveApp'
'onBannerDismiss'
    
// 以下事件，适用于全屏广告    
'onInterstitialFailedToReceive'
'onInterstitialReceive'
'onInterstitialPresent'
'onInterstitialLeaveApp'
'onInterstitialDismiss'

方法

AdMob.setOptions(options)

用途: 给其他的方法调用设置默认参数，所有的项目都是可选的，如果没有则用默认值。

参数:

  • options, json object, mapping key to value.

参数 options 的 key/value:

  • bannerId, string, 设置广告条的默认广告 ID，例如 'ca-app-pub-xxx/xxx'
  • interstitialId, string, 设置全屏广告的默认广告 ID，例如 'ca-app-pub-xxx/xxx'
  • adSize, string, 设置广告条的大小，默认值:'SMART_BANNER'. 可以是以下的某个: (效果参见截图)
'SMART_BANNER', // 推荐，自动适应屏幕大小和高度
'BANNER', 
'MEDIUM_RECTANGLE', 
'FULL_BANNER', 
'LEADERBOARD', 
'SKYSCRAPER', 
'CUSTOM', // 用于自定义大小，需要指定参数 'width' 和 'height'
  • width, integer, 广告条的宽度, 需要指定 adSize:'CUSTOM'. 默认值: 0
  • height, integer, 广告条的高度，需要指定 adSize:'CUSTOM'. 默认值: 0
  • overlap, *boolean@, 浮动模式，允许广告条覆盖在Web内容的上面，否则的话会把Webview向上或者向下推，避免遮挡. 默认值:false
  • position, integer, 广告条的位置，, 默认值:TOP_CENTER （上面居中）. 可选的值可以是:
AdMob.AD_POSITION.NO_CHANGE  	= 0,
AdMob.AD_POSITION.TOP_LEFT 		= 1,
AdMob.AD_POSITION.TOP_CENTER 	= 2,
AdMob.AD_POSITION.TOP_RIGHT 	= 3,
AdMob.AD_POSITION.LEFT 			= 4,
AdMob.AD_POSITION.CENTER 		= 5,
AdMob.AD_POSITION.RIGHT 		= 6,
AdMob.AD_POSITION.BOTTOM_LEFT 	= 7,
AdMob.AD_POSITION.BOTTOM_CENTER 	= 8,
AdMob.AD_POSITION.BOTTOM_RIGHT 	= 9,
AdMob.AD_POSITION.POS_XY 		= 10, // 用于指定位置 X 和 Y, 参见 'x' and 'y'
  • x, integer, x坐标. 当 overlap:true 和 position:AdMob.AD_POSITION.POS_XY 的时候有效. 默认值: 0
  • y, integer, y坐标. 当 overlap:true 和 position:AdMob.AD_POSITION.POS_XY 的时候有效. 默认值: 0
  • isTesting, boolean, 用于测试，当设置为 true 的时候，可以接收测试广告，发布的时候，请务必设置为 false，否则不计算收益。
  • autoShow, boolean, 当广告准备就绪时自动显示，否则需要调用 showBanner 或者 showInterstitial
  • orientationRenew, boolean, 在屏幕方向发生变化时，强制销毁和重新创建广告条，一般情况不用设置。
  • adExtras, json object, 为广告显示设置额外的色彩风格.
{
	color_bg: 'AAAAFF',
	color_bg_top: 'FFFFFF',
	color_border: 'FFFFFF',
	color_link: '000080',
	color_text: '808080',
	color_url: '008000'
}

例程:

var defaultOptions = {
	bannerId: admobid.banner,
	interstitialId: admobid.interstitial,
	adSize: 'SMART_BANNER',
	width: 360, // valid when set adSize 'CUSTOM'
	height: 90, // valid when set adSize 'CUSTOM'
	position: AdMob.AD_POSITION.BOTTOM_CENTER,
	x: 0,		// valid when set position to POS_XY
	y: 0,		// valid when set position to POS_XY
	isTesting: true,
	autoShow: true
};
AdMob.setOptions( defaultOptions );

AdMob.createBanner(adId/options, success, fail)

用途: 创建广告条. 这个方法可以传入广告的ID字符串，也可以传入Json对象以包含更多的选项。

参数

  • adId, string, 广告条的 ID.
  • options, json object, 可以附带参数选项，参见 AdMob.setOptions
  • success, function, 成功之后的回调函数，可以为 null 或者 缺失.
  • fail, function, 失败之后的回调函数，可以为 null 或者 缺失.

参数 options 可以有额外的选项：

  • adId, string, 广告条的 ID.
  • success, function, 成功之后的回调函数.
  • error, function, 失败之后的回调函数.

例程:

// 仅仅传入广告 ID，其他的用默认值
AdMob.createBanner( admobid.banner );

// 附带更多的参数
AdMob.createBanner({
	adId: admobid.banner,
	position: AdMob.AD_POSITION.BOTTOM_CENTER,
	autoShow: true,
	success: function(){
	},
	error: function(){
		alert('failed to create banner');
	}
});

AdMob.showBanner(position)

用途: 在指定的位置显示广告条. 也可以用来移动广告条，而无需销毁和重新创建广告条。

参数:

  • position, integer, 参见 AdMob.setOptions()

AdMob.showBannerAtXY(x, y)

用途: 在制定的坐标位置 (x,y) 显示广告条.

参数:

  • x, integer, 像素. 从屏幕左边计算的偏移量.
  • y, integer, 像素. 从屏幕顶端计算的偏移量.

AdMob.hideBanner()

用途: 隐藏广告条。暂时从屏幕上移除，但没有销毁，稍后还可以继续显示.

AdMob.removeBanner()

用途: 销毁广告条，不再显示时调用，例如用户已经付费，去掉广告。

AdMob.prepareInterstitial(adId/options, success, fail)

用途: 准备全屏广告资源，用于后续显示。

参数:

  • adId, string, 全屏广告的广告ID.
  • options, string, 参见 *AdMob.setOptions()
  • success, function, 成功之后的回调函数，可以为 null 或者 缺失.
  • fail, function, 失败之后的回调函数，可以为 null 或者 缺失.

参数 options 可以有额外的选项：

  • adId, string, 广告条的 ID.
  • success, function, 成功之后的回调函数.
  • error, function, 失败之后的回调函数.

友情提示: 通常全屏广告需要较多的图片资源比广告条稍多，因此流量也会稍多一点，通常需要一点点时间来准备，这样用户无需等待，体验会更好。

AdMob.showInterstitial()

用途: 当全屏广告准备就绪时，显示给用户看。

AdMob.isInterstitialReady(callback)

用途: 检查全屏广告资源是否已经准备就绪。通常无需调用，最佳方式是响应相关的事件。

例程:

// 准备，并且自动显示，大约需要0.5-1秒
AdMob.prepareInterstitial({
	adId: admobid.interstitial,
	autoShow: true
});

// 在游戏关卡开始的时候，准备广告资源
AdMob.prepareInterstitial({
	adId: admobid.interstitial,
	autoShow: false
});
// 在游戏关卡结束的时候，检查并且显示广告
AdMob.isInterstitialReady(function(isready){
	if(isready) AdMob.showInterstitial();
});

事件

广告条的事件

'onBannerFailedToReceive'

当从广告服务器加载广告资源失败的时候触发.

document.addEventListener('onBannerFailedToReceive',function(data){
	console.log( data.error + ',' + data.reason );
	AdMob.hideBanner();
});

'onBannerReceive'

当广告资源从服务器成功加载之后触发.

document.addEventListener('onBannerReceive',function(data){
	AdMob.showBanner();
});
AdMob.createBanner({
	adId: admobid.banner,
	autoShow: false
});

'onBannerPresent'

当广告成功显示出来的时候触发.

'onBannerLeaveApp'

当用户点击广告的时候，即将跳转到广告链接指向的网站时触发。也许，你可以计算用户点击了多少次。

'onBannerDismiss'

当广告被关闭，回到应用或者游戏的时候触发。

全屏广告的事件

  • 'onInterstitialFailedToReceive'
  • 'onInterstitialReceive'
  • 'onInterstitialPresent'
  • 'onInterstitialLeaveApp'
  • 'onInterstitialDismiss'

这几个事件，与广告条类似，不再赘述。

关于使用 Android Proguard 的提醒 （来自谷歌）##

为了避免把需要的类给处理掉，需要在 <project_directory>/platform/android/proguard-project.txt 文件中加入以下内容:

-keep class * extends java.util.ListResourceBundle {
    protected Object[][] getContents();
}

-keep public class com.google.android.gms.common.internal.safeparcel.SafeParcelable {
    public static final *** NULL;
}

-keepnames @com.google.android.gms.common.annotation.KeepName class *
-keepclassmembernames class * {
    @com.google.android.gms.common.annotation.KeepName *;
}

-keepnames class * implements android.os.Parcelable {
    public static final ** CREATOR;
}
Clone this wiki locally