---
name: godot-admob-migrate
description: Provides instructions to migrate your Godot AdMob project between different plugin versions (e.g. from version 4.x to version 5.x) in GDScript and C#. Use when upgrading plugin versions.
metadata:
  version: 1.0.0
  category: GodotAdMob
---
# Godot AdMob - Migration Guide

Assists with migrating your Godot AdMob integration between different plugin versions in GDScript and C#.

## Migrate from v4.x to v5.x

### Steps

1.  **Remove SMART_BANNER Constants**: Replace any references to `AdSize.SMART_BANNER` or `SmartBanner` with Anchored Adaptive Banner sizes.
2.  **Update Fallbacks**: Ensure that any legacy layouts using `-1, -1` size fallback values are replaced with the recommended Anchored Adaptive Banner sizes.
3.  **Android App ID Migration & config.gd Removal**:
    *   **Extract Android App ID**: Read the `APPLICATION_ID` constant from `res://addons/admob/android/config.gd` (if upgrading an existing project).
    *   **Save to Project Settings**: Transfer the Android App ID into `project.godot` under `[admob]` section as `general/android/app_id="your-app-id"` (or via **Project Settings > General > Admob**).
    *   **Remove config.gd**: `config.gd` is deprecated and removed in v5; all settings are now managed via Project Settings.
4.  **AdPosition Class Migration**: `AdPosition.Values` enum is replaced by `AdPosition` static instances (e.g. `AdPosition.TOP` or `AdPosition.custom(x, y)`). Update your code references.
5.  **iOS Export Cleanup & App ID Migration**:
    *   **Delete AdMob `.gdip` files & binaries**: Delete all legacy `poing-godot-admob*.gdip` files and the `res://ios/plugins/poing-godot-admob/` directory inside `res://ios/plugins/` (do not delete the outer `plugins/` folder if other non-AdMob plugins exist). Version 5 injects frameworks dynamically during export, so leaving old `.gdip` files and binaries will cause `Multiple commands produce ...` build errors in Xcode.
    *   **Transfer iOS App ID**: Move the iOS App ID (formerly set in `Gad Application Identifier` in Export Presets or `.gdip`) into `project.godot` under `[admob]` section as `general/ios/app_id="your-app-id"` (or via **Project Settings > General > Admob**).
    *   **Clear Export Presets**: Clear the `Gad Application Identifier` field and uncheck legacy AdMob plugin checkboxes in your iOS Export Preset settings to avoid duplicate injection.
6.  **Update Gradle Dependencies**: Clean and rebuild your Android plugin template if necessary to fetch the GMA Next-Gen SDK dependencies.
7.  **Review Initialization Defaults**: By default, initialization and ad loading optimizations are enabled. If you run into threading issues, toggle **Disable Initialization Optimization** and **Disable Ad Loading Optimization** in the Godot project settings under **Admob > General > Android**.
8.  **Download v5 Platform Binaries**: In the Godot Editor, open **AdMob Manager** and click **Download & Install** for both Android and iOS to download the new v5.0.0 native libraries. The export plugin will block project export if the installed native binaries are missing or legacy/v4 due to version mismatch protection.
9.  **Asynchronous SDK Initialization**: On Android (GMA Next-Gen SDK), initialization via `MobileAds.initialize()` is strictly asynchronous. You must wait for the callback (using `OnInitializationCompleteListener`) to fire before loading any ads. Attempting to load ads prior to initialization completion will throw an exception.

### Migration References

#### Size Migration

| Removed Constant (v4.x) | Recommended Alternative (v5.x) |
| :--- | :--- |
| `AdSize.SMART_BANNER` (GDScript) | `AdSize.get_current_orientation_anchored_adaptive_banner_ad_size(AdSize.FULL_WIDTH)` |
| `AdSize.SmartBanner` (C#) | `AdSize.GetCurrentOrientationAnchoredAdaptiveBannerAdSize(AdSize.FullWidth)` |

#### AdPosition Migration

| Removed Enum (v4.x) | Recommended Class Instance (v5.x) |
| :--- | :--- |
| `AdPosition.Values.TOP` (GDScript) | `AdPosition.TOP` |
| `AdPosition.Values.Top` (C#) | `AdPosition.Top` |
| Custom positions unsupported | `AdPosition.custom(x, y)` (GDScript) / `AdPosition.Custom(x, y)` (C#) |