مهاجرت با ابزارهای هوش مصنوعی (بتا)

# AI Migration Agent Instructions for the Google Mobile Ads SDK

## Migrate to the GMA Next-Gen SDK

* When I ask to migrate to the "Next-Gen" SDK, **ALWAYS** look up the latest
  stable version for
  `com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk`.
* Make sure the project meets the SDK requirements of `minSdk` 24 or higher
  and `compileSdk` of 35 or higher.
* Replace the `com.google.android.gms:play-services-ads` dependency with the
  Next-Gen `com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk`
  dependency.
* Resolve each `com.google.android.gms.ads.*` class to its specific
  counterpart in `com.google.android.libraries.ads.mobile.sdk.*`.
    * If the change involves the
      `com.google.android.gms.ads.mediation.Adapter` class, ask me if I'm
      sure I want to migrate this class before making the change.
* **CRITICAL:** `MobileAds.initialize()` must be called on a background thread.
* **CRITICAL:** Make sure `MobileAds.initialize()` is called **before** any
  other SDK methods (e.g., `MobileAds.setRequestConfiguration()`). Move any such
  calls to the initialization callback or after initialization is complete.
    * If `RequestConfiguration` is used, configure it using
      `InitializationConfig.Builder.setRequestConfiguration()` and pass the
      config to `MobileAds.initialize()`. Do not call
      `MobileAds.setRequestConfiguration()` separately before initialization.
* **CRITICAL:** **Always** dispatch UI-related operations (e.g., view
  updates, Toasts) within GMA Next-Gen SDK callbacks to the UI thread (e.g.,
  using `runOnUiThread` or `Main` dispatcher). This is MANDATORY as the GMA
  Next-Gen SDK callbacks are not guaranteed to be on the main thread.
* **ALWAYS** use the value of the `com.google.android.gms.ads.APPLICATION_ID`
  meta-data tag from `AndroidManifest.xml` for `applicationId`. If you can't
  find it, ask me what the AdMob application ID is.
* Preserve the `com.google.android.gms.ads.APPLICATION_ID` `<meta-data>` tag
  in the `AndroidManifest.xml` file.
* Run a build/compile check. If there are **0 errors** related to the files
  you modified, no more references to `com.google.android.gms.ads`, and
  you've verified every step in the instructions, consider the migration
  complete.

### Banner ads

* Declare the preferred
  `com.google.android.libraries.ads.mobile.sdk.banner.AdView` class to load
  a "Next-Gen" banner ad instead of the deprecated `BannerAd` APIs.
* To check if a banner ad is collapsible, use `getBannerAd().isCollapsible()` on
  the `AdView` object.

### Native ads

* The following APIs are now set on the `NativeAdRequest.Builder`:
  * `.setCustomFormatIds(customFormatIds: List<String>)`
  * `.disableImageDownloading()`
  * `.setMediaAspectRatio(mediaAspectRatio: NativeMediaAspectRatio)`
  * `.setAdChoicesPlacement(adChoicesPlacement: AdChoicesPlacement)`
  * `.setVideoOptions(videoOptions: VideoOptions)`
* Remove all "Mute This Ad" logic and associated data structures as they are not
  supported in the GMA Next-Gen SDK.

### Ad preloading

* Unless noted in the mapping table, Ad preloading methods are the same from the
  old SDK to the GMA Next-Gen SDK. The existing API signature stays the same,
  using the same parameters as before.

### API mapping

This table covers the main classes and their GMA Next-Gen SDK equivalents.

| Feature                    | Old SDK Import (`com.google.android.gms.ads...`)                                     | GMA Next-Gen SDK Import (`com.google.android.libraries.ads.mobile.sdk...` )                                                                                                           |
|:---------------------------|:-------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Core**                   |                                                                                      |                                                                                                                                                                                       |
| Initialization             | `MobileAds`                                                                          | `MobileAds`, `initialization.InitializationConfig`                                                                                                                                    |
| Ad Request                 | `AdRequest`                                                                          | *Format specific* (e.g. `common.AdRequest`, `banner.BannerAdRequest`, `nativead.NativeAdRequest`) (Ad Unit ID is declared in `Builder`. Load() no longer takes an activity)           |
| Load Error                 | `LoadAdError`                                                                        | `common.LoadAdError` (`LoadAdError` no longer has a domain variable. REMOVE the domain variable if found.)                                                                            |
| Full Screen Show Error     | `AdError` (within `FullScreenContentCallback`)                                       | `common.FullScreenContentError` (within format-specific `AdEventCallback`)                                                                                                            |
| Request Configuration      | `RequestConfiguration`                                                               | `common.RequestConfiguration` (Nested Enums/Constants for RequestConfiguration are now under common.RequestConfiguration.)                                                            |
| Event Callbacks            | `FullScreenContentCallback` (for full screen formats), `AdListener` (Banner, Native) | *Format Specific* (e.g., `interstitial.InterstitialAdEventCallback`, `banner.BannerAdEventCallback`, `native.NativeAdEventCallback`). Variable on the ad format is `adEventCallback`. |
| **Tools**                  |                                                                                      |                                                                                                                                                                                       |
| Ad Inspector               | `MobileAds.openAdInspector()`                                                        | `MobileAds.openAdInspector()` (`openAdInspector` no longer takes an activity)                                                                                                         |
| Ad Inspector Listener      | `OnAdInspectorClosedListener`                                                        | `common.OnAdInspectorClosedListener`                                                                                                                                                  |
| **Formats**                |                                                                                      |                                                                                                                                                                                       |
| App Open                   | `appopen.AppOpenAd`                                                                  | `appopen.AppOpenAd`                                                                                                                                                                   |
| App Open Load              | `appopen.AppOpenAd.AppOpenAdLoadCallback`                                            | `common.AdLoadCallback<appopen.AppOpenAd>`                                                                                                                                            |
| Banner                     | `AdView`, `AdSize`                                                                   | `banner.AdView`, `banner.AdSize` (`AdView` no longer has `pause()`, `resume()`, `setAdSize()`). `AdSize` is declared in `BannerAdRequest`.                                            |
| Banner Load                | `AdListener`                                                                         | `common.AdLoadCallback<banner.BannerAd>`                                                                                                                                              |
| Banner Events              | `AdListener`                                                                         | `banner.BannerAdEventCallback`, `banner.BannerAdRefreshCallback`                                                                                                                      |
| Interstitial               | `interstitial.InterstitialAd`                                                        | `interstitial.InterstitialAd`                                                                                                                                                         |
| Interstitial Load          | `interstitial.InterstitialAd.InterstitialAdLoadCallback`                             | `common.AdLoadCallback<interstitial.InterstitialAd>`                                                                                                                                  |
| Ad Loader                  | `AdLoader`                                                                           | `nativead.NativeAdLoader`                                                                                                                                                             |
| Native                     | `nativead.NativeAd`                                                                  | `nativead.NativeAd` (No longer has a `mediaView` variable)                                                                                                                            |
| Native Custom Format Ad    | `nativead.NativeCustomFormatAd`                                                      | `nativead.CustomNativeAd`                                                                                                                                                             |
| Native Custom Click        | `nativead.NativeCustomFormatAd.OnCustomClickListener`                                | `nativead.OnCustomClickListener` (set on the `CustomNativeAd` object (e.g., `.onCustomClickListener`)                                                                                 |
| Native Load                | `nativead.NativeAd.OnNativeAdLoadedListener`                                         | `nativead.NativeAdLoaderCallback`                                                                                                                                                     |
| Native Ad View             | `nativead.NativeAdView`                                                              | `nativead.NativeAdView`                                                                                                                                                               |
| Media Content              | `MediaContent`                                                                       | `nativead.MediaContent` (hasVideoContent is declared as a `val`)                                                                                                                      |
| Media Aspect Ratio         | `MediaAspectRatio`                                                                   | `nativead.MediaAspectRatio`                                                                                                                                                           |
| Video Options              | `VideoOptions`                                                                       | `common.VideoOptions`                                                                                                                                                                 |
| Video Controller           | `VideoController`                                                                    | `common.VideoController` (VideoLifecycleCallbacks is now an interface, so instantiate with `object : VideoController.VideoLifecycleCallbacks { ... }`)                                |
| Rewarded                   | `rewarded.RewardedAd`                                                                | `rewarded.RewardedAd`                                                                                                                                                                 |
| Rewarded Load              | `rewarded.RewardedAd.RewardedAdLoadCallback`                                         | `common.AdLoadCallback<rewarded.RewardedAd>`                                                                                                                                          |
| Rewarded Interstitial      | `rewardedinterstitial.RewardedInterstitialAd`                                        | `rewardedinterstitial.RewardedInterstitialAd`                                                                                                                                         |
| Rewarded Interstitial Load | `rewardedinterstitial.RewardedInterstitialAd.RewardedInterstitialAdLoadCallback`     | `common.AdLoadCallback<rewardedinterstitial.RewardedInterstitialAd>`                                                                                                                  |
| Paid Event Listener        | `OnPaidEventListener`                                                                | `common.AdEventCallback`                                                                                                                                                              |
| Response Info              | `ResponseInfo`                                                                       | `common.ResponseInfo` (property access is now `getResponseInfo()`. `loadedAdapterResponseInfo` is now `loadedAdSourceResponseInfo`.)                                                  |
| **Rewards**                |                                                                                      |                                                                                                                                                                                       |
| Reward Listener            | `OnUserEarnedRewardListener`                                                         | `rewarded.OnUserEarnedRewardListener`                                                                                                                                                 |
| Reward Item                | `rewarded.RewardItem`                                                                | `rewarded.RewardItem` (property access on `RewardedAd` and `RewardedInterstitialAd` is now `getRewardItem()`)                                                                         |
| Ad Value                   | `AdValue`                                                                            | `common.AdValue`                                                                                                                                                                      |
| **Preloading**             |                                                                                      |                                                                                                                                                                                       |
| Configuration              | `preload.PreloadConfiguration`                                                       | `common.PreloadConfiguration`                                                                                                                                                         |
| Callback                   | `preload.PreloadCallbackV2`                                                          | `common.PreloadCallback` (Now an interface instead of an abstract class)                                                                                                              |
| Interstitial Preloader     | `interstitial.InterstitialPreloader`                                                 | `interstitial.InterstitialAdPreloader`                                                                                                                                                |
| **Ad Manager**             |                                                                                      |                                                                                                                                                                                       |
| Ad Request                 | `admanager.AdManagerAdRequest`                                                       | `common.AdRequest` (Now directly implemented in the `AdRequest` class)                                                                                                                |
| Ad View                    | `admanager.AdView`                                                                   | `banner.AdView` (No `AdManagerAdView` class)                                                                                                                                          |
| App Event Listener         | `admanager.AppEventListener`                                                         | `common.OnAppEventListener`                                                                                                                                                           |

## Method mapping

This table covers the main methods and their GMA Next-Gen SDK equivalents.

| Feature                                  | Old SDK Method Signature                                                                                                                                                        | GMA Next-Gen SDK Method Signature                                                                                                                                                                                                                                                          |
|:-----------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Core**                                 |                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                            |
| MobileAds Initialization                 | `MobileAds.initialize(Context context, OnInitializationCompleteListener listener)`                                                                                              | `MobileAds.initialize(Context context, InitializationConfig config, OnInitializationCompleteListener listener)`                                                                                                                                                                            |
| InitializationConfig Builder             | N/A                                                                                                                                                                             | `InitializationConfig.Builder(String applicationId)`                                                                                                                                                                                                                                       |
| Ad Request Builder                       | `AdRequest.Builder().build()`                                                                                                                                                   | `AdRequest.Builder(String adUnitId).build()` (for App Open, Interstitial, Rewarded, Rewarded Interstitial) **Banner:** `BannerAdRequest.Builder(String adUnitId, AdSize adSize).build()` **Native:** `NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>).build()` |
| Add Network Extras (AdMobAdapter)        | `AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)`                                                                              | `AdRequest.Builder(String adUnitId).setGoogleExtrasBundle(Bundle extraBundle)`                                                                                                                                                                                                             |
| Add Network Extras (Ad Source Adapter)   | `AdRequest.Builder().addNetworkExtrasBundle(Class<MediationExtrasReceiver>, Bundle networkExtras)`                                                                              | `AdRequest.Builder(String adUnitId).putAdSourceExtrasBundle(Class<MediationExtrasReceiver> adapterClass, Bundle adSourceExtras)`                                                                                                                                                           |
| Custom Targeting                         | `AdRequest.Builder().setCustomTargeting(String key, String value)`                                                                                                              | `AdRequest.Builder(String adUnitId).putCustomTargeting(String key, String value)`                                                                                                                                                                                                          |
| **Formats**                              |                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                            |
| App Open                                 | `AppOpenAd.load(Context context, String adUnitId, AdRequest request, AppOpenAdLoadCallback loadCallback)`                                                                       | `AppOpenAd.load(AdRequest request, AdLoadCallback<AppOpenAd> loadCallback)`                                                                                                                                                                                                                |
| Banner                                   | `AdView.loadAd(AdRequest request)`                                                                                                                                              | `AdView.loadAd(BannerAdRequest request, AdLoadCallback<BannerAd> loadCallback)`                                                                                                                                                                                                            |
| Interstitial                             | `InterstitialAd.load(Context context, String adUnitId, AdRequest request, InterstitialAdLoadCallback loadCallback)`                                                             | `InterstitialAd.load(AdRequest request, AdLoadCallback<InterstitialAd> loadCallback)`                                                                                                                                                                                                      |
| Rewarded                                 | `RewardedAd.load(Context context, String adUnitId, AdRequest request, RewardedAdLoadCallback loadCallback)`                                                                     | `RewardedAd.load(AdRequest request, AdLoadCallback<RewardedAd> loadCallback)`                                                                                                                                                                                                              |
| Rewarded Interstitial                    | `RewardedInterstitialAd.load(Context context, String adUnitId, AdRequest request, RewardedInterstitialAdLoadCallback loadCallback)`                                             | `RewardedInterstitialAd.load(AdRequest request, AdLoadCallback<RewardedInterstitialAd> loadCallback)`                                                                                                                                                                                      |
| Native Builder                           | `AdLoader.Builder(Context context, String adUnitId).forNativeAd(NativeAd.OnNativeAdLoadedListener onNativeAdLoadedListener)`                                                    | `NativeAdRequest.Builder(String adUnitId, nativeAdTypes: List<NativeAdType>)` (Include `NativeAd.NativeAdType.NATIVE` in `nativeAdTypes`)                                                                                                                                                  |
| Native Load                              | `AdLoader.Builder(...).build().loadAd(AdRequest request)`                                                                                                                       | `NativeAdLoader.load(NativeAdRequest request, NativeAdLoaderCallback callback)`                                                                                                                                                                                                            |
| Native Ad Register                       | `NativeAdView.setNativeAd(NativeAd nativeAd)`                                                                                                                                   | `NativeAdView.registerNativeAd(NativeAd nativeAd, mediaView: MediaView?)`                                                                                                                                                                                                                  |
| Set an App Event Listener (Banner)       | `AdManagerAdView.appEventListener`                                                                                                                                              | `BannerAd.adEventCallback` (`onAppEvent(name: String, data: String?)` is now part of the `BannerAdEventCallback`)                                                                                                                                                                          |
| Set an App Event Listener (Interstitial) | `AdManagerInterstitialAd.appEventListener`                                                                                                                                      | `InterstitialAd.adEventCallback` (`onAppEvent(name: String, data: String?)` is now part of the `InterstitialAdEventCallback`)                                                                                                                                                              |
| **Callbacks**                            |                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                            |
| onAdOpened                               | `AdListener.onAdOpened()`                                                                                                                                                       | `AdEventCallback.onAdShowedFullScreenContent()`                                                                                                                                                                                                                                            |
| onAdClosed                               | `AdListener.onAdClosed()`                                                                                                                                                       | `AdEventCallback.onAdDismissedFullScreenContent()`                                                                                                                                                                                                                                         |
| onFailedToShowFullScreenContent          | `onAdFailedToShowFullScreenContent(adError: AdError)`                                                                                                                           | `onAdFailedToShowFullScreenContent(fullScreenContentError: FullScreenContentError)`                                                                                                                                                                                                        |
| onAdLoaded                               | **AdLoadCallback**: `onAdLoaded(ad: T)` (e.g., `InterstitialAdLoadCallback`, `RewardedAdLoadCallback`, `RewardedInterstitialAdLoadCallback`)                                    | Parameter name is always `ad` **Format specific**: `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)` (Format-specific e.g., `banner.BannerAdEventCallback.onAdPaid(value: AdValue)`)                                                                                                                                                                 |
| onVideoMute                              | `onVideoMute(muted: Boolean)`                                                                                                                                                   | `onVideoMute(isMuted: Boolean)`                                                                                                                                                                                                                                                            |
| onAdPreloaded                            | `onAdPreloaded(preloadId: String, responseInfo: ResponseInfo?)`                                                                                                                 | `onAdPreloaded(preloadId: String, responseInfo: ResponseInfo)`                                                                                                                                                                                                                             |
| **Preloading**                           |                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                            |
| Configuration                            | `PreloadConfiguration.Builder(String adUnitId).build()`                                                                                                                         | `PreloadConfiguration(AdRequest request)`                                                                                                                                                                                                                                                  |