Google Mobile Ads React Native API

@google/mobile-ads 模組提供核心 TypeScript 介面、類別和頂層函式，可將 Google Mobile Ads 整合至 React Native 應用程式。

總覽

型別別名
AdapterState
代表中介服務轉接程式的可能初始化狀態。
AdChoicesPlacement
廣告瀏覽畫面中 AdChoices 圖示的位置。
AdFormat
要求的廣告格式。
AdInspectorError
廣告檢查器失敗的相關錯誤資訊。
AdInspectorErrorCode
影響廣告檢查器開啟或運作的錯誤。
AdOrientation
內嵌自動調整和大型錨定自動調整橫幅廣告的螢幕方向選項。
AdSize
代表廣告的尺寸。
AgeRestrictedTreatment
定義廣告請求的年齡限制處理選項。
ConsentStatus
同意聲明狀態值。
DebugGeography
用於測試地理位置的偵錯值。
FormErrorCode
代表 User Messaging Platform (UMP) 表單作業失敗的錯誤代碼。
FullScreenContentErrorCode
LoadAdErrorCode
代表廣告載入作業失敗的錯誤代碼。
MaxAdContentRating
定義應用程式的廣告內容分級上限，並將可顯示的廣告類型分類。
NativeAdAssetNames
用於識別標準原生廣告素材資源的名稱。
NativeAdType
識別已載入原生廣告的格式。
NativeMediaAspectRatio
傳回原生廣告媒體的顯示比例偏好設定。
OnAdInspectorClosedListener
廣告檢查器 UI 關閉時要叫用的回呼介面定義。
PrecisionType
回報廣告價值的精確程度。
PrivacyOptionsRequirementStatus
隱私權選項規定狀態。
PublisherPrivacyPersonalizationState
指出發布商隱私權處理方式的個人化狀態。
ResizeMode
可自訂 NativeAdMediaView 中圖片內容的調整大小模式。
ResolvedAdSize
代表廣告載入後，廣告大小的最終解析狀態。
SwipeGestureDirection
自訂點擊滑動手勢的操作說明。
變數
AdSize
預先定義的廣告尺寸，以及用於建立自動調整和自訂尺寸的輔助方法。
函式
canRequestAds
檢查目前的同意聲明狀態是否允許您要求廣告。
getConsentStatus
取得使用者目前的同意聲明狀態。
getInitializationStatus
取得 SDK 初始化狀態。
getPrivacyOptionsRequirementStatus
檢查應用程式是否需要隱私權選項進入點。
getRequestConfiguration
取得全域要求設定。
initialize
初始化 Google Mobile Ads SDK。
isConsentFormAvailable
檢查是否有同意聲明表單。
loadAndShowConsentFormIfRequired
如果使用者目前的同意聲明狀態需要同意聲明表單 (例如狀態為 REQUIRED)，系統就會載入並向使用者顯示表單。
openAdInspector
開啟 Google Mobile Ads SDK 廣告檢查工具疊加層。
openDebugMenu
開啟偵錯選單。
parseLoadAdError
剖析廣告載入期間擲回的原生錯誤，並包裝在 LoadAdError 中。
requestConsentInfoUpdate
要求更新同意聲明資訊。
reset
清除永久儲存空間中的所有同意聲明狀態。
setPublisherFirstPartyIdEnabled
控管是否啟用發布商第一方 ID。
setRequestConfiguration
設定法規遵循和指定目標的全域要求設定。
setUserControlledAppVolume
設定使用者控制的應用程式音量。
setUserMutedApp
設定應用程式是否設為靜音。
showPrivacyOptionsForm
顯示隱私權選項表單。

型別別名

AdapterState

AdapterState: typeof AdapterState[keyof typeof AdapterState]
代表中介服務轉接程式的可能初始化狀態。
屬性
NOT_READY
表示中介服務轉接程式尚未初始化或初始化失敗。
READY
表示中介服務轉接程式已成功初始化，可放送廣告。

AdChoicesPlacement

AdChoicesPlacement: typeof AdChoicesPlacement[keyof typeof AdChoicesPlacement]
廣告瀏覽畫面中 AdChoices 圖示的位置。
屬性
BOTTOM_LEFT
廣告左下角。
BOTTOM_RIGHT
廣告右下角。
TOP_LEFT
廣告的左上角。
TOP_RIGHT
廣告右上角。

AdFormat

AdFormat: typeof AdFormat[keyof typeof AdFormat]
要求的廣告格式。
屬性
APP_OPEN
應用程式開啟頁面廣告格式。
BANNER
橫幅廣告格式。
INTERSTITIAL
插頁式廣告格式。
NATIVE
原生廣告格式。
REWARDED
獎勵廣告格式。
REWARDED_INTERSTITIAL
插頁式獎勵廣告格式。

AdInspectorError

AdInspectorError: BaseError<AdInspectorErrorCode>
廣告檢查器失敗的相關錯誤資訊。

AdInspectorErrorCode

AdInspectorErrorCode: typeof AdInspectorErrorCode[keyof typeof AdInspectorErrorCode]
影響廣告檢查器開啟或運作的錯誤。
屬性
ALREADY_OPEN
廣告檢查器已開啟，因此無法再次開啟。
FAILED_TO_LOAD
無法載入廣告檢查器。
INTERNAL_ERROR
廣告檢查器發生內部錯誤。
NOT_IN_TEST_MODE
裝置未處於測試模式，因此無法開啟廣告檢查器。

AdOrientation

AdOrientation: typeof AdOrientation[keyof typeof AdOrientation]
內嵌自動調整和大型錨定自動調整橫幅廣告的螢幕方向選項。
屬性
CURRENT
LANDSCAPE
PORTRAIT

AdSize

代表廣告的尺寸。

可能是預先定義的一組尺寸 (例如 AdSize.LARGE_BANNER)，也可能是自動調整大小。

AgeRestrictedTreatment

AgeRestrictedTreatment: typeof AgeRestrictedTreatment[keyof typeof AgeRestrictedTreatment]
定義廣告請求的年齡限制處理選項。
屬性
CHILD
表示廣告請求應採用兒童年齡處理方式。
TEEN
表示廣告請求應採用青少年年齡處理方式。
UNSPECIFIED
表示廣告請求不適用任何年齡限制處理信號。

ConsentStatus

ConsentStatus: typeof ConsentStatus[keyof typeof ConsentStatus]
同意聲明狀態值。
屬性
NOT_REQUIRED
不需提供同意聲明。
OBTAINED
已取得使用者同意聲明，個人化與非個人化廣告 undefined。
REQUIRED
需要取得使用者同意聲明，但尚未取得。
UNKNOWN
同意聲明狀態不明。

DebugGeography

DebugGeography: typeof DebugGeography[keyof typeof DebugGeography]
偵錯值，用於測試地理區域。
屬性
DISABLED
偵錯裝置已停用偵錯地理位置。
EEA
偵錯裝置的地理區域會顯示為歐洲經濟區。
OTHER
地理位置顯示為沒有強制執行調試裝置法規的區域。
REGULATED_US_STATE
對於偵錯裝置，地理位置會顯示為美國受管制的州。

FormErrorCode

FormErrorCode: typeof FormErrorCode[keyof typeof FormErrorCode]
代表 User Messaging Platform (UMP) 表單作業失敗的錯誤代碼。
屬性
ALREADY_USED
同意聲明表單已使用過。
INTERNAL_ERROR
SDK 內部發生錯誤。
INVALID_OPERATION
作業無效。
NETWORK_ERROR
網路連線問題導致表單作業失敗。
TIMEOUT
表單作業逾時。
UNAVAILABLE
沒有可用的同意聲明表單。
UNKNOWN
錯誤代碼無法對應至已知錯誤代碼。

FullScreenContentErrorCode

FullScreenContentErrorCode: typeof FullScreenContentErrorCode[keyof typeof FullScreenContentErrorCode]
屬性
AD_ALREADY_USED
廣告已顯示。
AD_NOT_READY
廣告尚未準備就緒，無法顯示。
AD_TOO_LARGE
廣告過大，無法顯示在場景中 (僅限 iOS)。
APP_NOT_FOREGROUND
應用程式不在前景。
INTERNAL_ERROR
發生內部錯誤，例如準備顯示廣告素材時發生例外狀況。
MEDIATION_ERROR
中介服務轉接程式無法顯示廣告。請參閱 FullScreenContentError.mediationAdError ，瞭解根本原因。
UNKNOWN
錯誤代碼無法對應至已知錯誤代碼。

LoadAdErrorCode

LoadAdErrorCode: typeof LoadAdErrorCode[keyof typeof LoadAdErrorCode]
代表廣告載入作業失敗的錯誤代碼。
屬性
AD_ALREADY_USED
廣告回應已用於載入廣告。
APP_ID_MISSING
缺少應用程式 ID，因此未提出廣告請求。
CANCELLED
廣告請求已取消 (僅限 Android)。
INTERNAL_ERROR
SDK 內部發生錯誤。
INVALID_REQUEST
廣告請求無效，例如廣告單元 ID 不正確。
INVALID_RESPONSE
伺服器對伺服器的廣告回應無效。舉例來說，廣告回應中沒有要求 ID。
MEDIATION_ERROR
找不到中介服務轉接程式，或無法執行廣告請求。
NETWORK_ERROR
網路連線問題導致廣告請求失敗。
NO_FILL
廣告請求發送成功，但廣告空間不足，因此未傳回廣告。
TIMEOUT
廣告請求逾時。
UNKNOWN
錯誤代碼無法對應至已知錯誤代碼。

MaxAdContentRating

MaxAdContentRating: typeof MaxAdContentRating[keyof typeof MaxAdContentRating]
定義應用程式的廣告內容分級上限，並將可顯示的廣告類型分類。
屬性
G
適合一般大眾，包括家庭和兒童。
MA
內容只適合成人觀眾。
PG
內容適合大多數觀眾 (需有家長陪伴輔導)。
T
內容適合青少年及年紀更長的觀眾。
UNSPECIFIED
未指定內容分級。

NativeAdAssetNames

NativeAdAssetNames: typeof NativeAdAssetNames[keyof typeof NativeAdAssetNames]
用於識別標準原生廣告素材資源的名稱。
屬性
ADCHOICES_CONTAINER_VIEW
AdChoices 疊加層的容器。
ADVERTISER
廣告主的名稱。
BODY
廣告的主要內文。
CALL_TO_ACTION
廣告的行動號召文字 (例如「安裝」或「瞭解詳情」)。
HEADLINE
廣告的標題。
ICON
廣告的圖示圖片。
MEDIA_CONTENT
廣告的主要媒體內容 (圖片或影片)。
PRICE
廣告中應用程式或產品的價格。
STAR_RATING
廣告宣傳的應用程式或產品星級評等。
STORE
商店名稱。

NativeAdType

NativeAdType: typeof NativeAdType[keyof typeof NativeAdType]
識別已載入原生廣告的格式。
屬性
BANNER
橫幅廣告。
CUSTOM_NATIVE
自訂原生格式廣告。
NATIVE
原生廣告。

NativeMediaAspectRatio

NativeMediaAspectRatio: typeof NativeMediaAspectRatio[keyof typeof NativeMediaAspectRatio]
傳回的原生廣告媒體顯示比例偏好設定。
屬性
ANY
不偏好傳回的原生廣告媒體顯示比例。
LANDSCAPE
要求傳回的原生廣告媒體採用橫向顯示比例。
PORTRAIT
要求傳回直向顯示比例的原生廣告媒體。
SQUARE
要求傳回顯示比例為正方形的原生廣告媒體。
UNKNOWN
長寬比不明。

OnAdInspectorClosedListener

OnAdInspectorClosedListener: ((error?) => void)
廣告檢查器 UI 關閉時要叫用的回呼介面定義。

PrecisionType

PrecisionType: typeof PrecisionType[keyof typeof PrecisionType]
回報的廣告價值精確度。
屬性
ESTIMATED
根據匯總資料預估的廣告價值。
PRECISE
為該廣告支付的精確價值。
PUBLISHER_PROVIDED
由發布商提供的廣告價值，例如中介服務群組中的手動千次曝光出價。
UNKNOWN
精確度不明的廣告價值。

PrivacyOptionsRequirementStatus

PrivacyOptionsRequirementStatus: typeof PrivacyOptionsRequirementStatus[keyof typeof PrivacyOptionsRequirementStatus]
隱私權選項規定狀態。
屬性
NOT_REQUIRED
不需要隱私權選項進入點。
REQUIRED
必須提供隱私權選項進入點。
UNKNOWN
隱私權選項規定狀態不明。

PublisherPrivacyPersonalizationState

PublisherPrivacyPersonalizationState: typeof PublisherPrivacyPersonalizationState[keyof typeof PublisherPrivacyPersonalizationState]
指出發布商隱私權處理方式的個人化狀態。
屬性
DEFAULT
表示廣告請求應採用發布商預設隱私權處理方式。
DISABLED
指出廣告請求應採用非個人化發布商隱私權處理方式。
ENABLED
表示廣告請求應採用個人化發布商隱私權處理方式。

ResizeMode

ResizeMode: typeof ResizeMode[keyof typeof ResizeMode]
可自訂 NativeAdMediaView 中圖片內容的調整大小模式。
屬性
CONTAIN
統一縮放圖片，使其符合檢視區塊大小。

圖片高度和寬度會一起縮放，因此每個維度都小於或等於檢視區塊的對應維度。圖片會縮放至檢視區塊內，不會扭曲顯示比例或遭到裁剪。
COVER
統一縮放圖片，使其涵蓋整個檢視區塊。

圖片高度和寬度會一起縮放，使每個維度等於或大於檢視區塊的對應維度。系統會裁剪圖片，使其符合檢視畫面，但不會扭曲顯示比例。
STRETCH
獨立縮放寬度和高度，填滿檢視畫面。

圖片高度和寬度會分別縮放，以符合檢視畫面的尺寸。圖片會縮放以填滿整個檢視畫面，但不會裁剪，且圖片的長寬比不會維持不變。

ResolvedAdSize

ResolvedAdSize: FixedAdSize | FluidAdSize
代表廣告載入後，廣告大小的最終解析狀態。

對大多數廣告而言，這會解析為具有確切 width 和 height 維度的 FixedAdSize。如果是動態調整大小的橫幅廣告，這會解析為 FluidAdSize，其中維度是由檢視區塊階層管理。

SwipeGestureDirection

SwipeGestureDirection: typeof SwipeGestureDirection[keyof typeof SwipeGestureDirection]
自訂點擊滑動手勢的指示。
屬性
DOWN
向下滑動。
LEFT
向左滑動。
RIGHT
向右滑動。
UP
向上滑動。

變數

AdSize

AdSize: {
  BANNER: FixedAdSize;
  custom: ((width, height) => FixedAdSize);
  FLUID: FluidAdSize;
  FULL_BANNER: FixedAdSize;
  getCurrentOrientationInlineAdaptiveBannerAdSize: ((width) => InlineAdaptiveAdSize);
  getInlineAdaptiveBannerAdSize: ((width, maxHeight) => InlineAdaptiveAdSize);
  getLandscapeInlineAdaptiveBannerAdSize: ((width) => InlineAdaptiveAdSize);
  getLargeAnchoredAdaptiveBannerAdSize: ((width) => Promise<LargeAnchoredAdaptiveAdSize>);
  getLargeLandscapeAnchoredAdaptiveBannerAdSize: ((width) => Promise<LargeAnchoredAdaptiveAdSize>);
  getLargePortraitAnchoredAdaptiveBannerAdSize: ((width) => Promise<LargeAnchoredAdaptiveAdSize>);
  getPortraitInlineAdaptiveBannerAdSize: ((width) => InlineAdaptiveAdSize);
  LARGE_BANNER: FixedAdSize;
  LEADERBOARD: FixedAdSize;
  MEDIUM_RECTANGLE: FixedAdSize;
}
預先定義的廣告尺寸，以及用於建立自動調整和自訂尺寸的輔助方法。

函式

canRequestAds

canRequestAds(): boolean
檢查目前的同意聲明狀態是否允許您要求廣告。
傳回
boolean true (如果可以要求廣告)， false 否則。

getConsentStatus

getConsentStatus(): ConsentStatus
取得使用者目前的同意聲明狀態。
傳回
ConsentStatus 目前的同意聲明狀態。

getInitializationStatus

getInitializationStatus(): InitializationStatus
取得 SDK 初始化狀態。

使用這個方法檢查 SDK 是否已完成初始化，並檢查個別中介服務轉接程式的狀態。
傳回
InitializationStatus 目前的初始化狀態。

getPrivacyOptionsRequirementStatus

getPrivacyOptionsRequirementStatus(): PrivacyOptionsRequirementStatus
檢查應用程式是否需要隱私權選項進入點。

如果需要進入點，請在應用程式中新增可見且可互動的 UI 元素，呼叫 showPrivacyOptionsForm 顯示隱私權選項表單。如果不需要進入點，請將 UI 元素設為不可見且無法互動。
傳回
PrivacyOptionsRequirementStatus 隱私權選項的規定狀態。

getRequestConfiguration

getRequestConfiguration(): RequestConfiguration
取得全域請求設定。

使用這個方法擷取目前已全域套用的請求設定。
傳回
RequestConfiguration 目前的全球請求設定。

initialize

initialize(config, onInitializationComplete?): void
初始化 Google Mobile Ads SDK。

請在載入廣告前，以及與 Google Mobile Ads SDK 的其餘部分互動前，呼叫這個方法。
參數
config: InitializationConfig 控制 SDK 初始化作業的選項。
Optional onInitializationComplete: ((status) => void) SDK 完成初始化時要執行的回呼函式。

isConsentFormAvailable

isConsentFormAvailable(): boolean
檢查是否有同意聲明表單。
傳回
boolean true (如有同意聲明表單)， false (否則)。

loadAndShowConsentFormIfRequired

loadAndShowConsentFormIfRequired(onDismissed?): void
如果使用者目前的同意聲明狀態需要同意聲明表單 (例如狀態為 REQUIRED)，系統就會載入並向使用者顯示表單。
參數
Optional onDismissed: ((error?) => void) 表單遭關閉或不需要表單時叫用的回呼函式，如果顯示失敗，則會提供選用的 FormError。

openAdInspector

openAdInspector(_listener): void
開啟 Google Mobile Ads SDK 廣告檢查器疊加層。

使用這個方法偵錯中介服務設定和廣告來源。
參數
_listener: OnAdInspectorClosedListener

openDebugMenu

openDebugMenu(adUnitId): void
開啟偵錯選單。

使用這個方法開啟特定廣告單元的偵錯選單，協助測試及排解廣告設定問題。
參數
adUnitId: string 要開啟偵錯選單的廣告單元 ID。

parseLoadAdError

parseLoadAdError(error): LoadAdError
剖析廣告載入期間擲回的原生錯誤，並將其包裝在 LoadAdError 中。
參數
error: unknown 原生模組擲回的錯誤物件。
傳回
LoadAdError 已剖析的 LoadAdError 物件。

requestConsentInfoUpdate

requestConsentInfoUpdate(params?, onComplete?): void
要求更新同意聲明資訊。

在每次應用程式工作階段中，都必須先呼叫這個 API，再呼叫 getConsentStatus。

呼叫這個 API 後，getConsentStatus 會同步更新回傳值，以保留先前應用程式工作階段的同意聲明狀態 (如有)。

在呼叫 onComplete 回呼後，getConsentStatus 可以再次更新為最新狀態。
參數
Optional params: ConsentRequestParameters 除錯和指定目標的選用設定。
Optional onComplete: ((error?) => void) 同意聲明資訊更新完成時叫用的回呼函式，如果要求失敗，則會提供選用的 FormError。

重設

reset(): void
清除永久儲存空間中的所有同意聲明狀態。

僅供偵錯使用。

setPublisherFirstPartyIdEnabled

setPublisherFirstPartyIdEnabled(enabled): void
控制是否啟用發布商第一方 ID。

啟用或停用 Google Mobile Ads SDK 發布商第一方 ID，舊稱「相同應用程式金鑰」。
另請參閱
參數
enabled: boolean 設為 true 可啟用發布商第一方 ID；設為 false 則會停用。預設值為 true。

setRequestConfiguration

setRequestConfiguration(_config): void
設定法規遵循和指定目標的全球請求設定。

使用這個方法指定指定目標詳細資料，例如廣告內容分級上限、法規遵循設定 (例如年齡處理標記) 和測試裝置 ID。
參數
_config: RequestConfiguration

setUserControlledAppVolume

setUserControlledAppVolume(volume): void
設定使用者控制的應用程式音量。

使用這個方法，相對於裝置上的其他音訊輸出，調整所有廣告的音量。
參數
volume: number 音量大小，介於 0.0 (靜音) 和 1.0 (最大音量)。 這個範圍內的任何浮點值都有效 (例如 0.001 或 0.33333)。值不限於特定步長增量，例如 0.1。

setUserMutedApp

setUserMutedApp(muted): void
設定應用程式是否靜音。

使用這個方法可控制後續廣告的初始音訊靜音狀態。
參數
muted: boolean 是否應將應用程式音訊設為靜音。預設值為 false。

showPrivacyOptionsForm

showPrivacyOptionsForm(onDismissed?): void
顯示隱私權選項表單。

如果 getPrivacyOptionsRequirementStatus 為 REQUIRED，系統就會顯示隱私權選項表單。

這個方法只能在回應使用者輸入內容時呼叫，要求顯示隱私權選項表單。

當表單可供使用時，SDK 會自動預先載入隱私權選項表單。如果沒有預先載入任何表單，SDK 會嘗試以非同步方式載入表單。

使用者看到表單、選取選項並關閉表單後，系統會呼叫 onDismissed 回呼。如果發生下列情況，函式也可能傳回 FormError：
  • 無法使用表單。
  • 表單無法顯示。
  • 表單仍在預先載入中。
參數
Optional onDismissed: ((error?) => void) 表單關閉時叫用的回呼函式，如果顯示失敗，則會提供選用的 FormError。