Mediation Network Development & Maintenance Guide

This guide outlines the architecture and step-by-step instructions for adding or maintaining AdMob mediation adapters (e.g., Meta, IronSource, Vungle, AppLovin) within the Godot AdMob Editor Plugin.

---

🏗️ Architecture Overview

Mediation integration consists of native Android/iOS libraries, GDScript/C# interface wrappers, and editor export configurations:

                  ┌────────────────────────────────┐
                  │          Game Project          │
                  └───────────────┬────────────────┘
                                  │ (API Calls)
                                  ▼
    ┌─────────────────────────────────────────────────────────────┐
    │                        Godot Addon                          │
    │  - AppLovin.gd (GDScript Wrapper)                           │
    │  - AppLovin.cs (C# Parity Wrapper)                          │
    │  - project_settings_service.gd (registers settings)         │
    │  - export_plugins (copies AARs/XCFrameworks)                │
    └──────────────────────┬──────────────────────────────┬───────┘
                           │ (JNI / Android Bridge)       │ (Objective-C++ / iOS Bridge)
                           ▼                              ▼
    ┌──────────────────────────────┐              ┌──────────────────────────────┐
    │        Android Library       │              │         iOS Framework        │
    │ - PoingGodotAdMobAppLovin.kt │              │ - PoingGodotAdMobAppLovin.mm │
    │ - play-services-ads-applovin │              │ - AppLovinAdapterTarget      │
    │ - AppLovin SDK (AAR)         │              │ - AppLovin SDK (XCFramework) │
    └──────────────────────────────┘              └──────────────────────────────┘

---

🛠️ Step-by-Step Implementation Guide

1. Editor Settings Registration

Add the setting to project_settings_service.gd:

SettingDefinition.new(ANDROID_MEDIATION_PREFIX + "network_name", TYPE_BOOL, false)

2. Public GDScript API Wrapper

Create <NetworkName>.gd inside platforms/godot_editor/addons/admob/gdscript/src/mediation/extras/<network_name>/:

• Must inherit MobileSingletonPlugin.
• Use type-safe := operators.
• Register under class name <NetworkName>.
• Add a setup and usage example in Main.gd inside _setup_mediation_adapters().

3. C# Wrapper Parity

Create <NetworkName>.cs in platforms/godot_editor/addons/admob/csharp/src/Mediation/Extras/<NetworkName>/:

• Match 1:1 API parity with the GDScript wrapper.
• Use PascalCase for method names, bridging to the snake_case GDScript plugin calls.
• Add a setup and usage example in MainCSharpExample.cs inside SetupMediationAdapters().

---

4. Android Native Implementation

1. Register Module: Add include ':src:mediation:<network_name>' to platforms/android/settings.gradle.
2. Build Configuration: Create build.gradle pulling dependencies from the GDScript config.
3. AndroidManifest: Create src/main/AndroidManifest.xml registering your org.godotengine.plugin.v2.PoingGodotAdMob<NetworkName> metadata.
4. Kotlin Plugin Class: Implement PoingGodotAdMob<NetworkName>(godot: Godot?) inheriting GodotPlugin and exposing methods annotated with @UsedByGodot.
5. Addon Export configuration:
   • Create config/poing_godot_admob_<network_name>.gd declaring your dependency coordinates (e.g., "com.google.ads.mediation:applovin:x.y.z.w").
   • Register the library name in export_plugin.gd (Android) arrays KNOWN_LIBS and MEDIATION_LIBS.

---

5. iOS Native Implementation

1. SCons Configuration: Modify SConstruct to add the new platform option to plugin and include the path to your .xcframework dependencies in FRAMEWORKPATH.
2. iOS GDIP Config:
   • Create config/poing-godot-admob-<network_name>.gdip under platforms/ios/src/mediation/<network_name>/config/ declaring SPM package rules.
   • Crucial SPM Tip: Swift Package Manager uses Semantic Versioning (major.minor.patch). For 4-component mediation versions (e.g., 13.6.3.0), multiply the patch component by 100 (e.g., use 13.6.300).
   • Create an identical copy under platforms/godot_editor/ios/plugins/ using the admob_packages array format.
3. Objective-C++ Wrapper:
   • Implement PoingGodotAdMob<NetworkName>.h & .mm referencing <NetworkNameSDK/NetworkNameSDK.h>.
   • Implement PoingGodotAdMob<NetworkName>Module.h & .mm to register the plugin singleton with the engine during initialization.

---

6. Create Documentation Page

Create a new Markdown documentation file <network_name>.md under docs/mediate/integrate_partner_networks/:

• Document the supported integrations (bidding/waterfall) and ad formats.
• Detail SDK imports for both Android and iOS.
• Describe how to enable the plugin in both Project Settings and Export Presets.
• Provide GDScript and C# code snippets for GDPR, CCPA, and any custom SDK configuration methods (such as audio controls).

---

🧪 Validation & Compilation

Android

Verify module compilation by running:

./gradlew build

iOS Swift Packages

Verify Swift Package Manager dependency resolution:

swift package resolve

iOS compilation

Compile the static library using SCons:

scons plugin=<network_name> arch=arm64 target=debug

Full Addon Rebuild

Generate and package all binaries into the editor addon directory using the main build script:

./scripts/build_local.sh all <godot_version>

Logging & Diagnostics

• Optional singletons (is_required := false): When a mediation plugin (like AppLovin) is disabled in Project Settings, the GDScript wrapper uses push_warning rather than printerr.
• Logcat visibility: In mobile builds (Android/iOS) without a debugger attached, Godot's push_warning is not outputted to standard console streams, meaning it will not appear in adb logcat logs. To force-print missing singleton messages to logcat, you must temporarily set is_required := true in the adapter wrapper initialization (which uses printerr).

---

🚫 Constraints & Security

• No Browser Usage: Do NOT launch browser subagents to research versions or view documentation. Always use terminal-based commands (such as curl, git ls-remote, or the native read_url_content tool) to inspect packages, repositories, or documentation pages.
• Consult Official Documentation: Before integrating any new mediation network, read the official Google AdMob mediation documentation for Android & iOS to ensure version compatibility. The URLs follow this pattern (replace <network_name> with the target mediation name in lowercase, e.g., vungle, bidmachine):
  • Android: https://developers.google.com/admob/android/mediation/<network_name>
  • iOS: https://developers.google.com/admob/ios/mediation/<network_name>
• Dependency Coordinates: Consult the dependency version tables in the official guides to retrieve the correct adapter coordinate (e.g., com.google.ads.mediation:<network_name>:<version>).
• Never Commit: Do not commit code or create branches unless explicitly instructed by the user.