市场place
作者 NativeScript.org
@nativescript/firebase-admob
由 NativeScript 团队制作 | v3.3.2
NativeScript Firebase - Admob
npm i --save @nativescript/firebase-admob

@nativescript/firebase-admob

一个插件，允许您通过将 Google 移动广告 SDK 集成到应用程序中来使您的 NativeScript 应用程序货币化。

注意：在使用此插件之前（如果尚未设置），请按照 @nativescript/firebase-core 中的说明设置您的应用程序以使用 Firebase。

@nativescript/firebase-admob 插件目前支持加载和显示以下广告类型

内容

安装

要安装 @nativescript/firebase-admob，请在项目根目录中运行以下命令

npm install @nativescript/firebase-admob

为 iOS 设置 Admob

在 App_Resources/iOS 的 Info.plist 文件中更新 GADApplicationIdentifier 键，其字符串值为您的 AdMob 应用 ID（在 AdMob UI 中 标识）。

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-3940256099942544~1458002511</string>

有关配置 Info.plist 和设置 App ID 的更多信息，请参阅 更新您的 Info.plist。

为 Android 设置 Admob

将 AdMob App ID（在 AdMob UI 中 标识）添加到应用程序的 AndroidManifest.xml 文件中，位于 App_Resources/Android/src/main。如果未这样做，则应用程序启动时将崩溃。通过添加具有名称 com.google.android.gms.ads.APPLICATION_ID 的 <meta-data> 标签来添加 ID，如下所示。对于 android:value，在引号中插入您自己的 AdMob App ID。

<application>
  <!-- Sample AdMob App ID: ca-app-pub-3940256099942544~3347511713 -->
  <meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"
  />
</application>

有关配置 AndroidManifest.xml 和设置 App ID 的更多信息，请参阅 配置您的应用程序。

使用 @nativescript/firebase-admob

要使用 @nativescript/firebase-admob 插件，请按照以下步骤操作

1. 初始化移动广告 SDK

在加载广告之前，通过在 Admob 类上调用静态 init 方法来初始化移动广告 SDK。建议在 main.ts 文件中在应用程序启动前调用此方法一次。

import { Admob } from '@nativescript/firebase-admob'

Admob.init()

2. 将您选择的广告格式添加到应用程序中

移动广告 SDK 已导入，您现在可以实施广告。单击下面的任何链接，以获取您所需广告格式的详细实现步骤。

横幅广告

横幅广告是出现在设备屏幕顶部或底部的矩形广告。在用户与应用互动时，它们会保持在屏幕上，并在一定时间后自动刷新。如果您是新手接触移动广告，这是一个很好的起点。

在开发模式下测试横幅广告

注意：在开发您的应用程序时，请确保使用测试广告而不是实际生产广告。如果不这样做，可能会导致您的账户被暂停。在发布应用程序之前，请确保用您的广告单元ID替换测试单元ID。

要启用专用的横幅测试广告单元ID，请访问以下链接

以下是在几种NativeScript版本中添加横幅广告的示例。

在 NativeScript Core 中添加横幅广告

在页面元素下注册插件命名空间（例如，前缀为ui），通过前缀从命名空间访问BannerAd视图并将其添加到XML中。

BannerAd需要设置以下属性

  • unitId
  • BannerAdSize：您可以在layoutChanged事件的回调函数中设置此值。有关更多信息，请参阅自定义横幅广告大小
  • 高度和宽度
<Page xmlns:ui="@nativescript/firebase-admob" >

  <StackLayout>
    <ui:BannerAd
      height="100"
      width="100"
      unitId="{{bannerAdUnit}}"
      layoutChanged="{{bannerLoaded}}"
/>
  </StackLayout>

在 NativeScript Angular 中添加横幅广告

通过将AdmobModule添加到您想要使用视图的组件的@NgModule装饰器的imports数组中，注册BannerAd视图。

import { AdmobModule } from '@nativescript/firebase-admob/angular';

@NgModule({
    imports: [
    AdmobModule
    ],
    declarations: [
        AppComponent
    ],
    bootstrap: [AppComponent]
})

接下来，将BannerAd视图添加到HTML中。BannerAd需要设置以下属性

  • unitId
  • BannerAdSize：您可以在layoutChanged事件的回调函数中设置此值。有关更多信息，请参阅自定义横幅广告大小
  • 高度和宽度
<BannerAd
  height="100"
  width="100"
  [unitId]="bannerAdUnit"
  (layoutChanged)="bannerLoaded($event)">
</BannerAd>

在 NativeScript Vue 中添加横幅广告

按照以下方式在app.ts文件中注册BannerAd视图

import { createApp } from 'nativescript-vue';
import Admob from '@nativescript/firebase-admob/vue'
import Home from './components/Home.vue';

const app = createApp(Home)
app.use(Admob)

然后按照以下方式将其添加到标记中。BannerAd需要设置以下属性

  • unitId
  • BannerAdSize：您可以在layoutChanged事件的回调函数中设置此值。有关更多信息，请参阅自定义横幅广告大小
  • 高度和宽度
<BannerAd
  height="100"
  width="100"
  :unitId="bannerAdUnit"
  @layoutChanged="bannerLoaded"/>

自定义横幅广告大小

要定义自定义横幅大小，您有2个选项

  • 使用所需的宽度和高度实例化BannerAdSize类，并将其设置为BannerAd的size属性。
import { BannerAdSize } from "@nativescript/firebase-admob"

const adSize = new BannerAdSize(300, 50)

banner.size = adSize
  • 将size设置为BannerAdSize类的任何常量。

下表列出了可用的常量和它们所表示的大小。

广告大小常量 大小（dp）（WxH） 描述
BANNER 320x50 标准横幅
LARGE_BANNER 320x100 大横幅
MEDIUM_RECTANGLE 320x250 中等矩形
FULL_BANNER 468x60 全尺寸横幅
LEADERBOARD 728x90 排行榜
createAnchoredAdaptiveBanner(width, orientation) 提供的宽度 x 自适应高度 自适应横幅
createInLineAdaptiveBanner(width, orientation) 提供的宽度 x 自适应高度 自适应横幅

监听横幅广告的生命周期事件

该插件允许您监听广告的不同生命周期事件，例如广告加载时。在调用load方法之前，注册事件处理程序。

const bannerView = event.object;

// Called when an ad is successfully received.
bannerView.on('adLoaded', (args) =>{
console.log('Ad loaded.'),
});

 // Called when an ad request failed.
bannerView.on('adFailedToLoad', (args) =>{
   console.log('Ad failed to load: ', args.error);
});

 // Called when the user removes an overlay that covers the screen.
bannerView.on('adClosed', (args) =>{
   console.log('Ad closed.');
});

 // Called when an impression occurs on the ad.
bannerView.on('adImpression', (args) =>{
   console.log('Ad impression.');
});

 // Called when an tap/touch/click occurs on the ad.
bannerView.on('adClicked', (args) =>{
   console.log('Ad tapped');
});

向用户显示横幅广告

要向用户显示横幅广告，获取BannerAd视图的引用，并在其上调用load方法。

bannerView.load()

添加横幅广告

横幅广告是全屏广告，直到用户关闭它，它都会覆盖应用程序界面。它们最好在应用程序执行的天然暂停时使用，例如在游戏的级别之间或任务完成后。

在开发模式下测试横幅广告

注意：当您的应用程序处于开发模式时，请确保使用测试广告而不是实际生产广告。如果不这样做，可能会导致您的账户被暂停。在发布应用程序之前，请确保用您的广告单元ID替换测试单元ID。要启用专用的测试广告单元ID，请访问以下链接

向用户显示横幅广告

要向用户显示横幅广告，请按照以下步骤操作

  1. 从@nativescript/firebase-admob导入InterstitialAd类。
import { InterstitialAd } from '@nativescript/firebase-admob'
  1. 创建横幅广告实例。

通过在类上调用静态方法createForAdRequest来创建横幅广告实例。createForAdRequest方法需要一个adUnitId，您可以选择传递一个RequestOptions对象。

import { InterstitialAd } from '@nativescript/firebase-admob'
const ad = InterstitialAd.createForAdRequest('ca-app-pub-3940256099942544/4411468910')
  1. 监听广告生命周期事件

要监听广告生命周期事件，例如广告显示或消失时，请在显示广告之前，在广告实例上调用 onAdEvent 方法，并传递一个回调函数来处理事件。

import { InterstitialAd } from '@nativescript/firebase-admob'
const ad = InterstitialAd.createForAdRequest('ca-app-pub-3940256099942544/4411468910')

ad.onAdEvent((event, error, data) => {
  switch (event) {
    case AdEventType.LOADED:
      break
    case AdEventType.CLOSED:
      break
    case AdEventType.OPENED:
      break
    case AdEventType.IMPRESSION:
      break
    case AdEventType.FAILED_TO_SHOW_FULL_SCREEN_CONTENT:
      break
  }
})
  1. 加载广告 您可以通过在广告实例上调用 load 方法来加载广告。
import { InterstitialAd } from '@nativescript/firebase-admob'
const ad = InterstitialAd.createForAdRequest('ca-app-pub-3940256099942544/4411468910')

ad.onAdEvent((event, error, data) => {
  switch (event) {
    case AdEventType.LOADED:
      break
    case AdEventType.CLOSED:
      break
    case AdEventType.OPENED:
      break
    case AdEventType.IMPRESSION:
      break
    case AdEventType.FAILED_TO_SHOW_FULL_SCREEN_CONTENT:
      break
  }
})

ad.load()
  1. 显示广告

要显示广告，请在广告实例上调用 show 方法。此方法在 load 方法之后调用。

import { InterstitialAd } from '@nativescript/firebase-admob'
const ad = InterstitialAd.createForAdRequest('ca-app-pub-3940256099942544/4411468910')

ad.onAdEvent((event, error, data) => {
  switch (event) {
    case AdEventType.LOADED:
      break
    case AdEventType.CLOSED:
      ad.show()
      break
    case AdEventType.OPENED:
      break
    case AdEventType.IMPRESSION:
      break
    case AdEventType.FAILED_TO_SHOW_FULL_SCREEN_CONTENT:
      break
  }
})

ad.load()

下一步

原生广告

原生广告是通过平台原生UI组件展示给用户的广告资产。它们使用与您构建布局相同的视图类型显示，并且可以格式化以匹配它们所在用户体验的视觉设计。在编码术语中，这意味着当原生广告加载时，您的应用程序会收到一个包含其资产的 NativeAd 对象，然后应用程序（而不是 Google 移动广告 SDK）负责显示它们。

在 NativeScript Core 中添加原生广告

要将原生广告添加到您的 {N} Core 应用程序中，请按照以下步骤操作

  1. 在页面元素下使用前缀 ui（这可以是任何名称）注册插件命名空间。
<Page xmlns:ui="@nativescript/firebase-admob" >

</Page>
  1. 使用前缀来访问 NativeAdView 并将其添加到标记中。
<Page xmlns:ui="@nativescript/firebase-admob" >
<ActionBar title="Admob" />
<StackLayout>

  <ui:NativeAdView height="400" loaded="{{nativeAdLoaded}}" />

</StackLayout>
</Page>

在开发模式下测试原生广告

注意：在开发应用程序时，请确保您使用测试广告单元 ID，而不是实时生产广告。未这样做可能导致您的账户被暂停。只需确保在发布应用程序之前将测试广告单元 ID 替换为您自己的广告单元 ID。

要启用专用测试广告单元 ID，请访问以下链接

  1. 在视图模型文件中从 @nativescript/firebase-admob 导入 NativeAdLoader 类。
import { NativeAdLoader } from '@nativescript/firebase-admob'

NativeAdLoader 类是管理原生广告的接口。

  1. 实例化 NativeAdLoader。通过调用其构造函数来创建 NativeAdLoader 的实例。构造函数接受 3 个参数。作为第一个参数的必需广告单元 ID，作为第二个和第三个参数的可选 RequestOptions 和 NativeAdOptions 对象。
const loader = new NativeAdLoader('ca-app-pub-3940256099942544/3986624511', null, {
  nativeAdOptions: {
    adChoicesPlacement: AdChoicesPlacement.TOP_RIGHT
  }
})
  1. 监听原生广告生命周期事件

要监听原生广告的 生命周期事件，当 NativeAdView 加载完毕时，在 NativeAdLoader 实例上调用 onAdEvent 方法。

<ui:NativeAdView height="400" loaded="{{ nativeAdLoaded }}">
  <GridLayout height="300" width="300">
    <Label id="headLineView" />
    <ui:MediaView id="mediaView" height="100%"/>
    <Label id="bodyView" />
    <Button id="callToActionView" />
  </GridLayout>
</ui:NativeAdView>
nativeAdLoaded(event){
const view = event.object;
loader.onAdEvent((event, error, data) => {
	if (event === NativeAdEventType.LOADED) {
		const ad = data as NativeAd;

		const headLineView = view.getViewById('headLineView');
		headLineView.text = ad.headline;
		const mediaView = view.getViewById('mediaView');
		view.mediaView = mediaView;
		mediaView.mediaContent = ad.mediaContent;
		const callToActionButton = view.getViewById('callToActionView');
		view.callToActionView = callToActionButton;
		callToActionButton.text = ad.callToAction;
		const bodyView = view.getViewById('bodyView');
		bodyView.text = ad.body;
		view.nativeAd = ad;
		console.log('nativead loaded');
	} else if (event === 'adFailedToLoad') {
		console.log('nativead failed to load', error);
	}
});
}
  1. 显示原生广告 要显示原生广告，请在 NativeAdLoader 实例上调用 load 方法。
loader.load()

NativeAdOptions 接口

使用 NativeAdOptions 对象设置原生广告的以下选项。

属性 类型 描述
returnUrlsForImageAssets 布尔值 可选：如果设置为 true，则 SDK 不会加载图像资产内容，可以使用原生广告图像 URL 来获取内容。默认值为 false。
multipleImages 布尔值 可选：某些图像资产包含一系列图像。将此属性设置为 true 告诉应用程序显示资产的所有图像。默认值 false（默认值）通知应用程序显示图像资产中的一系列图像的第一张图像。
adChoicesPlacement AdChoicesPlacement 可选：默认情况下，AdChoices 浮层 设置在右上角。应用程序可以通过设置此属性为以下值之一来更改此浮层渲染的角落
videoOptions videoOptions 可选：用于设置作为原生广告一部分返回的视频资产的选项。如果广告包含视频（如果 ad.mediaContent.hasVideoContent = true），则显示视频。
mediaAspectRatio MediaAspectRatio 可选：此操作设置原生广告返回的图片或视频的宽高比。

AdChoicesPlacement

enum AdChoicesPlacement {
	TOP_LEFT = 'topLeft',
	TOP_RIGHT = 'topRight',
	BOTTOM_RIGHT = 'bottomRight',
	BOTTOM_LEFT = 'bottomLeft',
}

videoOptions

videoOptions 属性是一个对象，具有以下属性

属性 类型 可选
startMuted 布尔值 是
clickToExpandRequested 布尔值 是
customControlsRequested 布尔值 是

MediaAspectRatio

enum MediaAspectRatio {
	LANDSCAPE = 'landscape',
	PORTRAIT = 'portrait',
	SQUARE = 'square',
	ANY = 'any',
}

这就完了！您的应用现在可以显示原生广告。

下一步

奖励广告

奖励广告是用户可以选择与之互动的广告，以换取应用内奖励 [1]。

在开发模式下测试奖励广告

注意：在开发您的应用程序时，请确保使用测试广告而不是实际生产广告。如果不这样做，可能会导致您的账户被暂停。在发布应用程序之前，请确保用您的广告单元ID替换测试单元ID。

要启用专用测试广告单元 ID，请访问以下链接

显示奖励广告

按照以下步骤显示奖励广告

  1. 从 @nativescript/firebase-admob 中导入 RewardedAd 类。
import { RewardedAd } from '@nativescript/firebase-admob'
  1. 创建一个 RewardedAd 实例

通过在 RewardedAd 类上调用 createForAdRequest 静态方法并传入广告单元 ID 来创建一个奖励广告实例。

import { RewardedAd } from '@nativescript/firebase-admob'
const ad = RewardedAd.createForAdRequest('ca-app-pub-3940256099942544/1712485313')
  1. 监听广告生命周期事件 在调用 load 方法加载广告之前，调用 onAdEvent 方法并传入一个回调函数来处理广告事件。
import { RewardedAd } from '@nativescript/firebase-admob'
const ad = RewardedAd.createForAdRequest('ca-app-pub-3940256099942544/1712485313')

ad.onAdEvent((event, error, data) => {
  if (event === AdEventType.LOADED) {
    console.log('rewarded', 'loaded')
  } else if (event === AdEventType.FAILED_TO_LOAD_EVENT) {
    console.error('loading error', error)
  }
})
  1. 加载广告 通过在 RewardAd 实例上调用 load 方法来加载广告。
import { RewardedAd } from '@nativescript/firebase-admob'
const ad = RewardedAd.createForAdRequest('ca-app-pub-3940256099942544/1712485313')

ad.onAdEvent((event, error, data) => {
  if (event === AdEventType.LOADED) {
    console.log('rewarded', 'loaded')
  } else if (event === AdEventType.FAILED_TO_LOAD_EVENT) {
    console.error('loading error', error)
  }
})
ad.load()
  1. 显示广告

要在屏幕上显示广告，请在广告实例上调用 show() 方法。

import { RewardedAd } from '@nativescript/firebase-admob'
const ad = RewardedAd.createForAdRequest('ca-app-pub-3940256099942544/1712485313')

ad.onAdEvent((event, error, data) => {
  if (event === AdEventType.LOADED) {
      console.log('rewarded', 'loaded')
      ad.show()
  } else if (event === AdEventType.FAILED_TO_LOAD_EVENT) {
    console.error('loading error', error)
  }
})
ad.load()

奖励广告事件

RewardAd 会发出以下生命周期事件，您可以监听它们

ad.onAdEvent((event, error, data) => {
  switch (event) {
    case AdEventType.LOADED:
      break
    case AdEventType.CLOSED:
      break
    case AdEventType.OPENED:
      break
    case AdEventType.IMPRESSION:
      break
    case AdEventType.FAILED_TO_SHOW_FULL_SCREEN_CONTENT:
      break
  }
})

当用户获得奖励时，会调用带有事件 rewarded_earned_reward 的 onAdEvent。务必实现此功能，并奖励用户观看广告。

定位

RequestConfiguration 对象收集每个广告请求的全局配置，并通过 firebase().admob().setRequestConfiguration() 应用。

儿童定向广告设置

有关儿童定向广告设置的信息，请参阅 儿童定向设置。

以下示例表明您希望将内容视为 COPPA 的儿童定向内容。

import { Admob, RequestConfiguration } from '@nativescript/firebase-admob';
const requestConfiguration: RequestConfiguration = {
  tagForChildDirectedTreatment: true
}
Admob.getInstance().requestConfiguration = requestConfiguration;

处理未成年用户广告请求

要处理未成年用户的广告请求，请参阅 未成年用户。

以下示例表明您希望将 TFUA 包含在您的广告请求中。

import { Admob, RequestConfiguration } from '@nativescript/firebase-admob';
const requestConfiguration: RequestConfiguration = {
  tagForUnderAgeOfConsent: true
}
Admob.getInstance().requestConfiguration = requestConfiguration;

如果启用儿童定向设置和 tagForUnderAgeOfConsent 的标签都设置为 true，则儿童定向设置优先。

广告内容过滤

此设置可以通过 RequestConfiguration.maxAdContentRating 设置。

对于这些请求返回的 AdMob 广告具有以下内容评级。此网络额外的可能值基于 数字内容标签分类，并且应该是以下 MaxAdContentRating 对象之一

  • MaxAdContentRating.G
  • MaxAdContentRating.PG
  • MaxAdContentRating.T
  • MaxAdContentRating.MA

以下代码配置了一个 RequestConfiguration 对象，指定返回的广告内容应与数字内容标签指定级别不高于 G 相对应

import { Admob, MaxAdContentRating, RequestConfiguration } from '@nativescript/firebase-admob';
const requestConfiguration: RequestConfiguration = {
  maxAdContentRating: MaxAdContentRating.G
}
Admob.getInstance().requestConfiguration = requestConfiguration;

许可

Apache License Version 2.0