Saltar a contenido

Migrar versiones del SDK

Esta página abarca migraciones para versiones actuales y anteriores del Godot AdMob Editor Plugin.

Migrar de v4 a v5

Las siguientes subsecciones describen cambios importantes, diferencias de comportamiento y nuevas APIs entre la versión principal 4 y 5 del Godot AdMob Editor Plugin.

Migración del SDK de Android Next-Gen

La versión 5.0.0 migra el plugin nativo de Android de la dependencia del SDK heredado de Google Mobile Ads al moderno SDK Google Mobile Ads Next-Gen:

  • Dependencia antigua (v4): com.google.android.gms:play-services-ads
  • Nueva dependencia (v5): com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk

Conflictos de Mediación

Dado que algunos adaptadores de mediación heredados de terceros pueden incluir de forma transitiva la antigua biblioteca play-services-ads o play-services-ads-lite, compilar su build de Android podría generar errores por clases o símbolos duplicados.

Solución Automática

El exportador de Godot en la versión 5.0.0 intercepta automáticamente el proceso de exportación de Android y corrige el archivo Gradle del proyecto (res://android/build/build.gradle o res://android/build/app/build.gradle) para excluir explícitamente las dependencias heredadas:

// Agregado automáticamente por Poing Godot AdMob Plugin para soportar GMA Next-Gen SDK
configurations.configureEach {
    exclude group: "com.google.android.gms", module: "play-services-ads"
    exclude group: "com.google.android.gms", module: "play-services-ads-lite"
}
No se requiere ninguna intervención o configuración manual.

Requisito de Inicialización Asíncrona del SDK

En la versión 5.0.0 (GMA Next-Gen SDK en Android), la inicialización del SDK a través de MobileAds.initialize() es estrictamente asíncrona.

  • Requisito: Debe esperar a que se complete la inicialización antes de cargar anuncios (por ejemplo, llamando a RewardedAdLoader.load() o AdView.load()).
  • Consecuencia: Intentar cargar anuncios antes de que se complete la inicialización generará una excepción no capturada: MobileAds.initialize must be called before using the Google Mobile Ads SDK.

Cómo Migrar

Pase un OnInitializationCompleteListener a MobileAds.initialize() y cargue sus anuncios solo cuando se active el callback de finalización.

Consultar el Estado de Inicialización

Si necesita consultar el estado de inicialización más tarde, puede usar el método MobileAds.get_initialization_status().

# Carga síncrona/inmediata heredada
MobileAds.initialize()
_load_rewarded_ad()

// Carga síncrona/inmediata heredada
MobileAds.Initialize();
LoadRewardedAd();

var init_listener := OnInitializationCompleteListener.new()
init_listener.on_initialization_complete = func(status: InitializationStatus) -> void:
    Log.info("Inicialización de AdMob completa. Cargando primer anuncio...")
    _load_rewarded_ad()

MobileAds.initialize(init_listener)

var onInitListener = new OnInitializationCompleteListener();
onInitListener.OnInitializationComplete = (status) => {
    GD.Print("Inicialización de AdMob completa. Cargando primer anuncio...");
    LoadRewardedAd();
};

MobileAds.Initialize(onInitListener);

Eliminación de Smart Banner

El formato heredado Smart Banner ha sido marcado como obsoleto por Google y se ha eliminado por completo del plugin en v5.

Lenguaje API de Tamaño Eliminada Reemplazo
GDScript AdSize.get_smart_banner_ad_size() AdSize.get_current_orientation_anchored_adaptive_banner_ad_size(width)
C# AdSize.GetSmartBannerAdSize() AdSize.GetCurrentOrientationAnchoredAdaptiveBannerAdSize(width)

Retrocompatibilidad de Respaldo

Por seguridad, tanto el plugin nativo de Android como el de iOS implementan un respaldo automático: si una escena o diseño antiguo sigue enviando un tamaño de ancho -1 y altura -1, el puente nativo lo intercepta y devuelve un tamaño estándar de Banner Adaptativo Anclado que coincide con el ancho de la pantalla.

Cómo Migrar

Usa Banners Adaptativos Anclados en su lugar. Son el reemplazo moderno oficial, calculando dinámicamente la altura óptima según el ancho del dispositivo y la densidad de pantalla.

# Smart banner heredado
var ad_view := AdView.new(unit_id, AdSize.get_smart_banner_ad_size(), AdPosition.Values.TOP)

// Smart banner heredado
var adView = new AdView(unitId, AdSize.GetSmartBannerAdSize(), AdPosition.Values.Top);

# Banner adaptativo que coincide con el ancho total
var ad_size := AdSize.get_current_orientation_anchored_adaptive_banner_ad_size(AdSize.FULL_WIDTH)
var ad_view := AdView.new(unit_id, ad_size, AdPosition.TOP)

// Banner adaptativo que coincide con el ancho total
var adSize = AdSize.GetCurrentOrientationAnchoredAdaptiveBannerAdSize(AdSize.FullWidth);
var adView = new AdView(unitId, adSize, AdPosition.Top);

Cambios en la API de AdPosition (Cambio Importante)

En la versión 5.0.0, la API de AdPosition cambió de un enum de enteros básico a una instancia de clase. Esto permite posicionar los anuncios de banner utilizando coordenadas estáticas predefinidas o desplazamientos de píxeles personalizados.

API v4 (Obsoleta) API v5 (Reemplazo)
AdPosition.Values.TOP AdPosition.TOP
AdPosition.Values.BOTTOM AdPosition.BOTTOM
AdPosition.Values.LEFT AdPosition.LEFT
AdPosition.Values.RIGHT AdPosition.RIGHT
AdPosition.Values.TOP_LEFT AdPosition.TOP_LEFT
AdPosition.Values.TOP_RIGHT AdPosition.TOP_RIGHT
AdPosition.Values.BOTTOM_LEFT AdPosition.BOTTOM_LEFT
AdPosition.Values.BOTTOM_RIGHT AdPosition.BOTTOM_RIGHT
AdPosition.Values.CENTER AdPosition.CENTER
Posicionamiento personalizado no soportado AdPosition.custom(x, y)

Cómo Migrar

Actualiza las creaciones de tus banners y actualizaciones de posición para pasar instancias de la clase AdPosition en lugar de los valores brutos del enum.

var ad_view := AdView.new(unit_id, ad_size, AdPosition.Values.TOP)

var adView = new AdView(unitId, adSize, AdPosition.Values.Top);

# Posición predefinida
var ad_view := AdView.new(unit_id, ad_size, AdPosition.TOP)

# Coordenadas personalizadas (ej. x=0, y=100)
var custom_ad_view := AdView.new(unit_id, ad_size, AdPosition.custom(0, 100))

// Posición predefinida
var adView = new AdView(unitId, adSize, AdPosition.Top);

// Coordenadas personalizadas (ej. x=0, y=100)
var customAdView = new AdView(unitId, adSize, AdPosition.Custom(0, 100));

Cambios en el Ecosistema de Mediación

El ecosistema de mediación se ha limpiado y actualizado. Los socios de mediación obsoletos se han eliminado y ahora se admiten varias redes nuevas.

Redes de Mediación Eliminadas

El siguiente adaptador de mediación heredado se ha eliminado debido a su obsolescencia:

  • AdColony

Redes de Mediación Agregadas

Se ha introducido soporte para las siguientes redes de mediación:

  • AppLovin
  • BidMachine
  • Chartboost
  • DT Exchange
  • i-mobile
  • InMobi
  • IronSource
  • LINE
  • Unity Ads

Nuevos Formatos de Anuncios

La versión 5.0.0 agrega soporte de primera clase para dos nuevos formatos de anuncios:

  1. Anuncios de Abertura de la Aplicación (App Open Ads): Se muestran cuando los usuarios abren o reanudan la aplicación. Se cargan mediante AppOpenAdLoader y se controlan usando AppOpenAd.
  2. Anuncios de Native Overlay: Permiten renderizar anuncios nativos personalizables directamente sobre el juego utilizando plantillas nativas (diseños Small o Medium) personalizadas con estilos (NativeTemplateStyle, NativeAdOptions).

Nuevas Configuraciones Globales y Funciones de Privacidad

Se han agregado varios métodos nuevos de API a la clase MobileAds y UserMessagingPlatform para el consentimiento, el cumplimiento de la privacidad y la depuración:

  • Ad Inspector: Abre el Ad Inspector mediante MobileAds.open_ad_inspector(ad_inspector_closed_listener).
  • Opción de ID de Primera Parte: Activa o desactiva el ID de primera parte del editor con MobileAds.set_publisher_first_party_id_enabled(enabled).
  • Preferencia de Cookies de Consentimiento: Configura si el SDK tiene consentimiento para cookies mediante MobileAds.set_gad_has_consent_for_cookies(enabled) y consúltalo con get_gad_has_consent_for_cookies().
  • Desactivar Reportes de Bloqueos (solo iOS): Evita que el SDK de Mobile Ads capture y envíe reportes de bloqueos mediante MobileAds.disable_sdk_crash_reporting().
  • Opciones de Privacidad UMP: Muestra el formulario de opciones de configuración de privacidad bajo demanda mediante UserMessagingPlatform.show_privacy_options_form(on_privacy_options_form_dismissed) y consulta su estado usando ConsentInformation.get_privacy_options_requirement_status().

Configuración Unificada en los Ajustes del Proyecto

En la versión 5.0.0, el plugin ha unificado todas las opciones de configuración directamente en los Ajustes del Proyecto (Project Settings) nativos de Godot, bajo la sección admob/. Esto reemplaza cualquier flujo de configuración heredado o entradas de menú de editor personalizadas.

Cambio de Configuración Importante: config.gd Eliminado

En la versión 4, el AdMob App ID se configuraba modificando el script de configuración estática ubicado en res://addons/admob/android/config.gd.

En la versión 5, el archivo config.gd ha sido completamente eliminado. Debes transferir tus App IDs a la nueva ubicación en los Ajustes del Proyecto.

Cambio Crítico en iOS: Elimine Archivos .gdip Heredados de v4 (Para Evitar Conflictos en Xcode)

En la versión 4, los plugins de iOS se registraban mediante archivos de configuración .gdip ubicados en res://ios/plugins/. En la versión 5, los frameworks y dependencias de iOS se agregan dinámicamente mediante el plugin del editor durante la exportación.

Debe eliminar todos los archivos heredados poing-godot-admob*.gdip y el directorio res://ios/plugins/poing-godot-admob/. (No elimine el directorio res://ios/plugins/ en sí si utiliza otros plugins de iOS que no sean de AdMob). No eliminar los archivos .gdip y binarios antiguos de AdMob provocará errores de símbolos y frameworks duplicados (Multiple commands produce ...) en Xcode.

Cambio Crítico en iOS: Limpie las Opciones de Exportación Heredadas (Para Evitar Conflictos)

En la versión 5, ya no necesita configurar manualmente el Gad Application Identifier ni marcar las opciones de plugins antiguos en las opciones del Preset de Exportación de iOS. El plugin lee automáticamente el App ID desde los Ajustes del Proyecto e inyecta los frameworks necesarios y el GADApplicationIdentifier en el Info.plist de su proyecto Xcode durante la exportación.

Es crítico que limpie estos campos antiguos y desmarque las opciones heredadas de AdMob en su Preset de Exportación de iOS. De lo contrario, se producirán errores de símbolos duplicados y conflictos de plugins.

Obligatorio: Actualizar Binarios Nativos de la Plataforma

Después de actualizar los archivos del plugin del editor (GDScript/C#) en su proyecto, debe abrir el AdMob Manager en el Editor de Godot y hacer clic en Download & Install para ambas plataformas (Android e iOS) para descargar los binarios nativos v5.0.0 correspondientes.

Si intenta exportar el proyecto con binarios nativos heredados (v4) o faltantes, el plugin de exportación bloqueará la exportación y mostrará un error para evitar cierres inesperados en tiempo de ejecución.

Las opciones de configuración ahora se registran y configuran en Ajustes del Proyecto > General:

  • Configuración de Android: admob/general/android/enabled, admob/general/android/app_id y banderas de optimización.
  • Configuración de iOS: admob/general/ios/enabled y admob/general/ios/app_id.
  • Redes de Mediación: Todos los socios de mediación se activan o desactivan globalmente mediante banderas booleanas bajo admob/mediation/ (ej. admob/mediation/applovin, admob/mediation/meta, etc.).

General Settings Mediation Settings

Instalador Dinámico de Binarios Headless (CI/CD)

Para soportar builds de CI headless sin empaquetar grandes binarios nativos en Git, v5.0.0 incluye un descargador síncrono:

  • Al ejecutarse en un entorno headless (como GitHub Actions), el plugin verifica automáticamente si faltan los binarios de las plataformas Android/iOS.
  • Descarga y extrae automáticamente estos binarios de manera dinámica a partir de los lanzamientos oficiales del repositorio durante el inicio del plugin.