From 2788987dfea23f9079b503434097a20efdbe7ec8 Mon Sep 17 00:00:00 2001 From: Mobile Ads Developer Relations Date: Wed, 15 Jul 2026 06:57:06 -0700 Subject: [PATCH] No public description PiperOrigin-RevId: 948311445 --- AGENTS.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..fb1795a9d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,128 @@ +# Google Mobile Ads (GMA) Unity Plugin — Agent Guidelines + +## Project Overview + +The Google Mobile Ads (GMA) Unity Plugin lets Unity developers serve mobile ads +on Android and iOS without writing Java or Objective-C code directly in their +game scripts. The plugin provides a C# interface (`GoogleMobileAds.Api`) that +wraps the native Android (`com.google.android.gms.ads`) and iOS +(`GoogleMobileAds`) SDKs. + +- **Primary Codebase**: + `google3/java/com/google/android/libraries/admob/demo/unity/googlemobileads/` +- **Open-Source Repository**: Synchronized to GitHub + (`googleads/googleads-mobile-unity`) using Copybara rules defined in + `opensource/copy.bara.sky`. + +## Architecture + +The plugin follows a 3-layer bridge architecture: + +1. **C# API (`GoogleMobileAds.Api` / `Common`)**: Game developer-facing classes + (`BannerView`, `InterstitialAd`, `RewardedAd`, `MobileAds`). +2. **Platform Bridges (`GoogleMobileAds.Platforms`)**: + - **Android (`Platforms/Android/`)**: Uses `AndroidJavaClass`, + `AndroidJavaObject`, and `AndroidJavaProxy` (`Utils.cs`) to interop with + the Android JVM. + - **iOS (`Platforms/iOS/`)**: Uses P/Invoke `[DllImport("__Internal")]` + (`Externs.cs`) to call native Objective-C C-linkage functions, and + `[MonoPInvokeCallback]` delegates for callbacks. +3. **Native Plugin Libs (`Assets/Plugins/`)**: + - **Android**: `Assets/Plugins/Android/GoogleMobileAdsPlugin.androidlib/` + containing Java bridge classes (`com.google.unity.ads.*`). + - **iOS**: Objective-C/Swift native wrapper sources and headers. + +## Key Files & Entry Points + +- `BUILD`: Main Blaze build targets (`unitypackage_public`, `basic_unittests`, + `gmscore_package`). +- `source/plugin/Assets/GoogleMobileAds/Api/MobileAds.cs`: Entry point for SDK + initialization and configuration. +- `source/plugin/Assets/GoogleMobileAds/Common/Utils.cs`: C# / Java / ObjC + type conversion helpers. +- `source/plugin/Assets/GoogleMobileAds/Editor/PListProcessor.cs`: Xcode + post-build hook (`[PostProcessBuild]`) injecting App IDs and SKAdNetwork + items into `Info.plist`. +- `source/plugin/Assets/GoogleMobileAds/Editor/GradleProcessor.cs`: Android + build hook editing `build.gradle` and managing NextGen dependencies. +- `source/plugin/Assets/GoogleMobileAds/Editor/IntegrationManager/IntegrationManagerWindow.cs`: + Modern UI Elements-based Editor window (`Google Mobile Ads > Manage + Mediation`) for managing mediation adapters. +- `source/plugin/Assets/GoogleMobileAds/Editor/MediationManager/PackageDataHandler.cs`: + Backend handler querying OpenUPM and Unity Package Manager (`UPM`) for + mediation adapters. +- `opensource/copy.bara.sky`: Defines public export workflow, EAP comment + stripping, and internal path exclusions. + +## Build & Test Commands + +### Building the Unity Package + +To build the public `.unitypackage` with full iOS cross-compilation support: + +```bash +blaze --blazerc=/google/src/head/depot/google3/java/com/google/android/gmscore/blaze/blazerc build //java/com/google/android/libraries/admob/demo/unity/googlemobileads:unitypackage_public --config=gmscore_sdk --config=ios_common --ios_multi_cpus=arm64,x86_64 --ios_minimum_os=13.0 --copt=-Wno-unguarded-availability-new --config=apple_cross_compile +``` + +### Running Unit Tests + +To run the basic C# unit tests (using NSubstitute mocks) and Android Java bridge +tests: + +```bash +blaze test //java/com/google/android/libraries/admob/demo/unity/googlemobileads:basic_unittests +``` + +## Gotchas & Anti-Patterns + +1. **EDM4U Dependency Trap**: Do **NOT** add precompiled External Dependency + Manager for Unity (EDM4U) DLLs (like `Google.VersionHandler.dll`) to `BUILD` + `srcs` to satisfy compiler warnings. Doing so forces untracked binaries into + the build input and breaks headless Forge / Test Welder execution. +2. **Unity 2019.4 IStyle Shorthand Ban**: Unity 2019.4 UIElements `IStyle` does + not support shorthand properties (`borderRadius`, `borderWidth`, + `borderColor`). Setting them throws compilation errors (`CS1061`). Always + expand to individual side properties (`borderLeftWidth`, + `borderTopLeftRadius`, etc.). +3. **Headless `EditorWindow` Crashes**: Never put UI layout logic directly + inside an `EditorWindow` class if that window or tool will be tested in + headless mode (`Test Welder` / Forge). `EditorWindow` cannot be instantiated + in batch mode (`NullReferenceException`). Extract layout into a + `VisualElement` subclass view. +4. **Guarding Native Editor APIs**: Native graphical Editor APIs + (`EditorGUIUtility.IconContent` or texture loaders) throw + `TypeInitializationException` in headless mode due to missing graphical + contexts. Always wrap these calls in `try-catch` blocks in UI view classes + with clean text fallbacks (`"ⓘ"` or `"X"`). +5. **Headless Click Simulation**: Standard `button.SendEvent(new ClickEvent())` + fails in headless mode because layout bounds are zero (`NaN`), failing the + `ContainsPoint` check. To simulate clicks synchronously in tests, use C# + reflection to invoke the private `clicked` delegate on `button.clickable`. +6. **OpenUPM Dictionary Deserialization**: Unity's `JsonUtility` does not + deserialize C# `Dictionary`. Do not rely on dictionary + deserialization for OpenUPM payload parsing in `PackageDataHandler.cs`; use + strongly-typed serializable structs. +7. **Unity .meta Files & GUIDs**: Unity requires matching `.meta` files and + unique GUID registration in `internal/guids.json` whenever new C# scripts or + Editor assets are added. Failing to register new GUIDs breaks presubmits and + package generation. +8. **EAP Code Stripping**: Internal-only or Early Access Program (EAP) features + inside public classes must be wrapped in `// START_EAP_STRIP` and `// + END_EAP_STRIP` comments so Copybara strips them before public release. + +## Task-Based Routing + +If your task involves... | Then investigate... +:---------------------------------------------------- | :------------------ +Adding or moving C# / Editor scripts | `development.md` +Building the package or running unit tests | `building_and_testing.md` +Creating or modifying Editor UI / Integration Manager | `IntegrationManagerWindow.cs`, `PackageDataHandler.cs` +Modifying open-source sync or adding internal files | `opensource/copy.bara.sky` +NextGen SDK clients (`NextGen*Client.cs`) | `source/plugin/Assets/GoogleMobileAds/Platforms/Android/NextGen*` and `GradleProcessor.cs` +iOS post-process build injections | `source/plugin/Assets/GoogleMobileAds/Editor/PListProcessor.cs` + +## Available Skills & Rules + +Skills placed inside `_agents/skills//SKILL.md` and rules inside +`_agents/rules/*.md` are automatically discovered and loaded by Jetski when +working in this repository.