google-mobile-ads-android-migrate-to-next-gen

Google Mobile Ads SDK の AI 移行エージェント向け手順

移行ワークフロー

このチェックリストで移行の進捗を管理します。

• Gradle の設定：

  • com.google.android.gms:play-services-ads を、最新の安定版 com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk に置き換えます。Maven に直接アクセスできない場合は、次のコマンドを実行して最新バージョンを取得します。latest タグで返されるバージョンが、GMA Next-Gen SDK の最新バージョンです。

    curl -sS https://dl.google.com/dl/android/maven2/com/google/android/libraries/ads/mobile/sdk/ads-mobile-sdk/maven-metadata.xml | sed -n 's/.*<latest>\(.*\)<\/latest>.*/\1/p'
    

  • minSdk（24 以上）と compileSdk（34 以上）を更新します。

  • シンボルの重複エラーを避けるため、アプリレベルのビルドファイルで、すべての依存関係から play-services-ads と play-services-ads-lite をグローバルに除外します。

  • 次の手順に進む前に、Gradle を同期します。

• ファイル単位の移行：
  • API マッピングとメソッドマッピングの表に従ってコードベースをリファクタリングし、インポート、クラス名、メソッドシグネチャを GMA Next-Gen SDK に移行します。
• 検証とビルド：
  • gradle build -x test を実行して、クリーンビルドが成功することを確認します。GMA SDK 関連のコンパイルエラーを解決します。

移行の基本ルール

• アプリ ID の使用：InitializationConfig の applicationId には、AndroidManifest.xml の com.google.android.gms.ads.APPLICATION_ID メタデータタグの値を必ず使用します。
  • 制約：マニフェスト内の <meta-data> タグは保持してください。User Messaging Platform SDK を使用するパブリッシャーには引き続き必要です。
• 初期化の順序：
  1. バックグラウンドスレッドで MobileAds.initialize() を呼び出します。
  2. 他の SDK メソッドを呼び出す前に initialize() が呼び出されるようにします。
  3. RequestConfiguration を使用する場合は、InitializationConfig.Builder.setRequestConfiguration() に渡します。初期化前に MobileAds.setRequestConfiguration() を呼び出してはいけません。
• UI スレッド処理：必須：GMA Next-Gen SDK のコールバックはバックグラウンドスレッドで呼び出されます。GMA SDK のコールバック内で、UI に関するすべての操作（Toast、View の更新、Fragment トランザクションなど）は、runOnUiThread {} または Dispatchers.Main.launch {} でラップする必要があります。この手順を省略すると、アプリケーションがクラッシュします。
• メディエーション：com.google.android.gms.ads.mediation.Adapter を実装するクラスでは、引き続き com.google.android.gms.ads を使用する必要があります。

形式ごとの詳細

バナー広告

• GMA Next-Gen SDK のバナーを読み込むには、com.google.android.libraries.ads.mobile.sdk.banner.AdView を使用します。
• バナーが折りたたみ可能かどうかを確認するには、次の API を使用します。 adView.getBannerAd().isCollapsible()。

ネイティブ広告

• NativeAdLoader：NativeAdLoader は抽象クラスであり、インスタンス化できません。静的に使用します（例：NativeAdLoader.load(...)）。
• 次の API は NativeAdRequest.Builder で設定するようになりました。
  • .setCustomFormatIds(customFormatIds: List<String>)
  • .disableImageDownloading()
  • .setMediaAspectRatio(mediaAspectRatio: NativeMediaAspectRatio)
  • .setAdChoicesPlacement(adChoicesPlacement: AdChoicesPlacement)
  • .setVideoOptions(videoOptions: VideoOptions)
• 削除：「この広告をミュート」するすべてのロジックを削除します。GMA Next-Gen SDK ではサポートされていません。
• MediaView：NativeAd には mediaView 変数が直接ありません。registerNativeAd(nativeAd, mediaView) を使用して、広告をビューに関連付けます。

広告のプリロード

• マッピング表に特記がない限り、GMA Next-Gen SDK の広告プリロードメソッドは、Old SDK と同じ API シグネチャとパラメーターを維持しています。

API マッピング

この表では、主要なクラスと、GMA Next-Gen SDK における対応クラスを示します。

機能	旧 SDK のインポート（com.google.android.gms.ads...）	GMA 次世代 SDK のインポート（com.google.android.libraries.ads.mobile.sdk... ）
コア
初期化	MobileAds	MobileAds, initialization.InitializationConfig
初期化リスナー	initialization.OnInitializationCompleteListener	initialization.OnAdapterInitializationCompleteListener
広告リクエスト	AdRequest	フォーマット固有（例：common.AdRequest、banner.BannerAdRequest、nativead.NativeAdRequest）（広告ユニット ID は Builder で宣言します。Load() でアクティビティを渡す必要はなくなりました）
読み込みエラー	LoadAdError	common.LoadAdError（LoadAdError に domain 変数はなくなりました。見つかった場合は domain 変数を削除してください。）
全画面表示エラー	AdError（FullScreenContentCallback 内）	common.FullScreenContentError（フォーマット固有の AdEventCallback 内）
リクエスト設定	RequestConfiguration	common.RequestConfiguration（RequestConfiguration のネストされた列挙型／定数は、common.RequestConfiguration の下に配置されるようになりました。）
イベントコールバック	FullScreenContentCallback（全画面フォーマット用）、AdListener（バナー、ネイティブ）	フォーマット固有（例：interstitial.InterstitialAdEventCallback、banner.BannerAdEventCallback、native.NativeAdEventCallback）。広告フォーマット上の変数名は adEventCallback です。
ツール
広告インスペクター	MobileAds.openAdInspector()	MobileAds.openAdInspector()（openAdInspector でアクティビティを渡す必要はなくなりました）
広告インスペクターリスナー	OnAdInspectorClosedListener	common.OnAdInspectorClosedListener
フォーマット
アプリ起動時広告	appopen.AppOpenAd	appopen.AppOpenAd
アプリ起動時広告の読み込み	appopen.AppOpenAd.AppOpenAdLoadCallback	common.AdLoadCallback<appopen.AppOpenAd>
バナー	AdView、AdSize	banner.AdView、banner.AdSize（AdView に pause()、resume()、setAdSize() はなくなりました）。AdSize は BannerAdRequest で宣言します。
バナーの読み込み	AdListener	common.AdLoadCallback<banner.BannerAd>
バナーイベント	AdListener	banner.BannerAdEventCallback、banner.BannerAdRefreshCallback
インタースティシャル	interstitial.InterstitialAd	interstitial.InterstitialAd
インタースティシャルの読み込み	interstitial.InterstitialAd.InterstitialAdLoadCallback	common.AdLoadCallback<interstitial.InterstitialAd>
広告ローダー	AdLoader	nativead.NativeAdLoader
ネイティブ	nativead.NativeAd	nativead.NativeAd（mediaView 変数はなくなりました）
ネイティブカスタムフォーマット広告	nativead.NativeCustomFormatAd	nativead.CustomNativeAd
ネイティブカスタムクリック	nativead.NativeCustomFormatAd.OnCustomClickListener	nativead.OnCustomClickListener（CustomNativeAd オブジェクトに設定します（例：.onCustomClickListener）
ネイティブの読み込み	nativead.NativeAd.OnNativeAdLoadedListener	nativead.NativeAdLoaderCallback
ネイティブ広告ビュー	nativead.NativeAdView	nativead.NativeAdView
メディアコンテンツ	MediaContent	nativead.MediaContent（hasVideoContent は val として宣言されています）
メディアのアスペクト比	MediaAspectRatio	nativead.MediaAspectRatio
動画オプション	VideoOptions	common.VideoOptions
動画コントローラー	VideoController	common.VideoController（VideoLifecycleCallbacks はインターフェースになりました。そのため、object : VideoController.VideoLifecycleCallbacks { ... } としてインスタンス化します）
リワード	rewarded.RewardedAd	rewarded.RewardedAd
リワード広告の読み込み	rewarded.RewardedAd.RewardedAdLoadCallback	common.AdLoadCallback<rewarded.RewardedAd>
リワード付きインタースティシャル	rewardedinterstitial.RewardedInterstitialAd	rewardedinterstitial.RewardedInterstitialAd
リワード付きインタースティシャルの読み込み	rewardedinterstitial.RewardedInterstitialAd.RewardedInterstitialAdLoadCallback	common.AdLoadCallback<rewardedinterstitial.RewardedInterstitialAd>
有料イベントリスナー	OnPaidEventListener	common.AdEventCallback
レスポンス情報	ResponseInfo	common.ResponseInfo
アダプターレスポンス情報	AdapterResponseInfo	common.AdSourceResponseInfo
リワード
リワードリスナー	OnUserEarnedRewardListener	rewarded.OnUserEarnedRewardListener
リワードアイテム	rewarded.RewardItem	rewarded.RewardItem（RewardedAd および RewardedInterstitialAd のプロパティアクセスは getRewardItem() になりました）
広告価値	AdValue	common.AdValue
事前読み込み
設定	preload.PreloadConfiguration	common.PreloadConfiguration
コールバック	preload.PreloadCallbackV2	common.PreloadCallback（抽象クラスではなくインターフェースになりました）
インタースティシャルの事前読み込み	interstitial.InterstitialPreloader	interstitial.InterstitialAdPreloader
Ad Manager
広告リクエスト	admanager.AdManagerAdRequest	common.AdRequest（AdRequest クラスに直接実装されるようになりました）
広告ビュー	admanager.AdView	banner.AdView（AdManagerAdView クラスはありません）
アプリイベントリスナー	admanager.AppEventListener	common.OnAppEventListener

メソッドの対応付け

この表では、主なメソッドと、それに対応する GMA Next-Gen SDK のメソッドをまとめています。

機能	旧 SDK のメソッドシグネチャ	GMA Next-Gen SDK のメソッドシグネチャ
コア
MobileAds の初期化	MobileAds.initialize(Context context, OnInitializationCompleteListener listener)	MobileAds.initialize(Context context, InitializationConfig config, OnInitializationCompleteListener listener)
InitializationConfig ビルダー	該当なし	InitializationConfig.Builder(String applicationId)
広告リクエストビルダー	AdRequest.Builder().build()	AdRequest.Builder(String adUnitId).build()（アプリ起動時、インタースティシャル、リワード、リワードインタースティシャルの場合） バナー： BannerAdRequest.Builder(String adUnitId, AdSize adSize).build() ネイティブ： NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>).build()
ネットワークエクストラの追加（AdMobAdapter）	AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)	AdRequest.Builder(String adUnitId).setGoogleExtrasBundle(Bundle extraBundle)
ネットワークエクストラの追加（広告ソースアダプター）	AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)	AdRequest.Builder(String adUnitId).putAdSourceExtrasBundle(Class<MediationExtrasReceiver> adapterClass, Bundle adSourceExtras)
カスタムターゲティング	AdRequest.Builder().setCustomTargeting(String key, String value)	AdRequest.Builder(String adUnitId).putCustomTargeting(String key, String value)
フォーマット
アプリ起動時	AppOpenAd.load(Context context, String adUnitId, AdRequest request, AppOpenAdLoadCallback loadCallback)	AppOpenAd.load(AdRequest request, AdLoadCallback<AppOpenAd> loadCallback)
バナー	AdView.loadAd(AdRequest request)	AdView.loadAd(BannerAdRequest request, AdLoadCallback<BannerAd> loadCallback)
インタースティシャル	InterstitialAd.load(Context context, String adUnitId, AdRequest request, InterstitialAdLoadCallback loadCallback)	InterstitialAd.load(AdRequest request, AdLoadCallback<InterstitialAd> loadCallback)
リワード	RewardedAd.load(Context context, String adUnitId, AdRequest request, RewardedAdLoadCallback loadCallback)	RewardedAd.load(AdRequest request, AdLoadCallback<RewardedAd> loadCallback)
リワードインタースティシャル	RewardedInterstitialAd.load(Context context, String adUnitId, AdRequest request, RewardedInterstitialAdLoadCallback loadCallback)	RewardedInterstitialAd.load(AdRequest request, AdLoadCallback<RewardedInterstitialAd> loadCallback)
ネイティブビルダー	AdLoader.Builder(Context context, String adUnitId).forNativeAd(NativeAd.OnNativeAdLoadedListener onNativeAdLoadedListener)	NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>)（nativeAdTypes に NativeAd.NativeAdType.NATIVE を含めます）
ネイティブの読み込み	AdLoader.Builder(...).build().loadAd(AdRequest request)	NativeAdLoader.load(NativeAdRequest request, NativeAdLoaderCallback callback)
ネイティブ広告の登録	NativeAdView.setNativeAd(NativeAd nativeAd)	NativeAdView.registerNativeAd(NativeAd nativeAd, mediaView: MediaView?)
アプリイベントリスナーの設定（バナー）	AdManagerAdView.appEventListener	BannerAd.adEventCallback（onAppEvent(name: String, data: String?) は BannerAdEventCallback の一部になりました）
アプリイベントリスナーの設定（インタースティシャル）	AdManagerInterstitialAd.appEventListener	InterstitialAd.adEventCallback（onAppEvent(name: String, data: String?) は InterstitialAdEventCallback の一部になりました）
コールバック
onAdOpened	AdListener.onAdOpened()	AdEventCallback.onAdShowedFullScreenContent()
onAdClosed	AdListener.onAdClosed()	AdEventCallback.onAdDismissedFullScreenContent()
onFailedToShowFullScreenContent	onAdFailedToShowFullScreenContent(adError: AdError)	onAdFailedToShowFullScreenContent(fullScreenContentError: FullScreenContentError)
onAdLoaded	AdLoadCallback：onAdLoaded(ad: T)（例：InterstitialAdLoadCallback、RewardedAdLoadCallback、RewardedInterstitialAdLoadCallback）	パラメーター名は常に ad です。フォーマット固有： onAdLoaded(ad: InterstitialAd)、onAdLoaded(ad: RewardedAd)、onAdLoaded(ad: RewardedInterstitialAd)
onAdFailedToLoad	onAdFailedToLoad(loadAdError: LoadAdError)	onAdFailedToLoad(adError: LoadAdError)
onCustomFormatAdLoaded	OnCustomFormatAdLoadedListener.onCustomFormatAdLoaded(NativeCustomFormatAd ad)	NativeAdLoaderCallback.onCustomNativeAdLoaded(CustomNativeAd customNativeAd)
onPaidEventListener	OnPaidEventListener.onPaidEvent(AdValue value)	AdEventCallback.onAdPaid(value: AdValue)（フォーマット固有。例：banner.BannerAdEventCallback.onAdPaid(value: AdValue)）
onVideoMute	onVideoMute(muted: Boolean)	onVideoMute(isMuted: Boolean)
onAdPreloaded	onAdPreloaded(preloadId: String, responseInfo: ResponseInfo?)	onAdPreloaded(preloadId: String, responseInfo: ResponseInfo)
プリロード
設定	PreloadConfiguration.Builder(String adUnitId).build()	PreloadConfiguration(AdRequest request)
レスポンス情報
レスポンス情報の取得	ad.responseInfo	ad.getResponseInfo()
読み込み済みアダプターのレスポンス情報	responseInfo.getLoadedAdapterResponseInfo()	responseInfo.loadedAdSourceResponseInfo
アダプターのレスポンスの取得	responseInfo.getAdapterResponses()	responseInfo.adSourceResponses
メディエーションアダプタークラスの取得	responseInfo.getMediationAdapterClassName()	responseInfo.adapterClassName
アダプターのレスポンス情報
広告ソース ID	AdapterResponseInfo.getAdSourceId()	AdSourceResponseInfo.id
広告ソース名	AdapterResponseInfo.getAdSourceName()	AdSourceResponseInfo.name
広告ソースのインスタンス ID	AdapterResponseInfo.getAdSourceInstanceId()	AdSourceResponseInfo.instanceId
広告ソースのインスタンス名	AdapterResponseInfo.getAdSourceInstanceName()	AdSourceResponseInfo.instanceName