@backsoul/capacitor-google-admob

Capacitor plugin for Google AdMob (Google Mobile Ads SDK) on iOS and Android, with TypeScript types and stable event names for tooling and search (e.g. “Capacitor AdMob banner interstitial rewarded app open native advanced”).

Supported formats (parity with AdMob “create ad unit”)

| Format | Methods | Notes | |--------|---------|--------| | Banner | showBanner, hideBanner, removeBanner | Adaptive banner + fixed sizes; anchored to safe area. | | Interstitial | loadInterstitial, showInterstitial | Full-screen; load then show. | | Rewarded | loadRewarded, showRewarded | User earns reward via listener. | | Rewarded interstitial | loadRewardedInterstitial, showRewardedInterstitial | Beta in some consoles; same load/show pattern. | | App open | loadAppOpen, showAppOpen | For production, follow Google’s cold/hot start guidance. | | Native Advanced | showNativeAdvanced, hideNativeAdvanced | NativeAdView / GADNativeAdView overlay; nativeAdvancedHeightChanged for WebView padding. |

Install

npm install @backsoul/capacitor-google-admob
npx cap sync

iOS

• Info.plist: GADApplicationIdentifier = your AdMob app ID (ca-app-pub-xxxxxxxx~yyyyyyyy).
• CocoaPods: add to Podfile inside capacitor_pods (adjust path to node_modules):

pod 'BacksoulCapacitorGoogleAdmob', :path => '../../node_modules/@backsoul/capacitor-google-admob'

Then pod install.

Android

• AndroidManifest / strings.xml: com.google.android.gms.ads.APPLICATION_ID with the same app ID.
• npx cap sync android links the Gradle module automatically.

Uso por tipo de anuncio

Importación común:

import {
  BacksoulGoogleAdmob,
  BACKSOUL_ADMOB_EVENTS,
} from '@backsoul/capacitor-google-admob';
import { Capacitor } from '@capacitor/core';

Las unidades de prueba oficiales de Google (solo desarrollo) están documentadas en Ads / pruebas. Sustituye por tus IDs reales de AdMob en producción.

1. Inicialización (una vez al arrancar la app)

async function setupAds() {
  if (!Capacitor.isNativePlatform()) return;

  await BacksoulGoogleAdmob.initialize({
    // Opcional: IDs de dispositivo de prueba (logcat / Xcode muestran el hash)
    testDeviceIds: ['YOUR_HASHED_DEVICE_ID'],
  });
}

2. Banner (rectangular, parte del layout nativo)

Ocupa una franja en la ventana (no dentro del HTML del WebView). Suele ir arriba o abajo; margin ayuda a no tapar tabs o el notch.

// Mostrar banner adaptativo abajo, con margen sobre la barra inferior
await BacksoulGoogleAdmob.showBanner({
  adUnitId: 'ca-app-pub-3940256099942544/6300978111', // ejemplo test banner
  adSize: 'ADAPTIVE_BANNER',
  position: 'BOTTOM_CENTER',
  margin: 92,
  isTesting: true,
});

// Escuchar tamaño para reservar padding en ion-content / scroll
const hBanner = await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.BANNER_SIZE_CHANGED,
  (p) => {
    const height = Number(p.height ?? 0);
    document.documentElement.style.setProperty('--ad-banner-padding', `${height}px`);
  }
);

// Ocultar sin destruir (sigue cargado)
await BacksoulGoogleAdmob.hideBanner();

// Quitar del todo y liberar
await BacksoulGoogleAdmob.removeBanner();
await hBanner.remove();

Posiciones: TOP_CENTER | CENTER | BOTTOM_CENTER.
Tamaños: ADAPTIVE_BANNER (recomendado), BANNER, LARGE_BANNER, MEDIUM_RECTANGLE, FULL_BANNER, LEADERBOARD, SMART_BANNER.

3. Intersticial (pantalla completa entre pantallas)

Flujo típico: precargar en un punto tranquilo y mostrar al cambiar de nivel / cerrar pantalla (no en medio de interacción crítica).

async function preloadInterstitial() {
  await BacksoulGoogleAdmob.loadInterstitial({
    adUnitId: 'ca-app-pub-3940256099942544/1033173712', // test interstitial
    isTesting: true,
  });
}

await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.INTERSTITIAL_LOADED,
  () => console.log('Interstitial listo')
);
await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.INTERSTITIAL_FAILED_TO_LOAD,
  (e) => console.warn('Fallo carga', e)
);
await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.INTERSTITIAL_DISMISSED,
  () => {
    // Usuario cerró el anuncio: navegar o precargar otro
    void preloadInterstitial();
  }
);

// Cuando quieras mostrar (p. ej. tras `router.navigate`)
await BacksoulGoogleAdmob.showInterstitial();

4. Bonificado / Rewarded (el usuario mira el vídeo a cambio de recompensa)

Precarga, muestra y escucha la recompensa en rewardedEarned.

await BacksoulGoogleAdmob.loadRewarded({
  adUnitId: 'ca-app-pub-3940256099942544/5224354917', // test rewarded
  isTesting: true,
});

await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.REWARDED_EARNED,
  (payload) => {
    const type = String(payload.type ?? '');
    const amount = Number(payload.amount ?? 0);
    // Entregar monedas / vidas / premium temporal
    console.log('Recompensa:', type, amount);
  }
);
await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.REWARDED_DISMISSED,
  () => console.log('Cerrado')
);

await BacksoulGoogleAdmob.showRewarded();

5. Intersticial bonificado / Rewarded interstitial (beta en consola)

Misma idea que rewarded, con otra unidad en AdMob.

await BacksoulGoogleAdmob.loadRewardedInterstitial({
  adUnitId: 'ca-app-pub-3940256099942544/5354046379', // test rewarded interstitial
  isTesting: true,
});

await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.REWARDED_INTERSTITIAL_EARNED,
  (payload) => {
    console.log('RI reward', payload.type, payload.amount);
  }
);

await BacksoulGoogleAdmob.showRewardedInterstitial();

6. App open (al abrir la app o volver del background)

Patrón recomendado por Google: cargar con loadAppOpen y mostrar con showAppOpen cuando la app pase a primer plano y no haya otra pantalla de anuncio. Aquí solo el flujo mínimo del plugin:

await BacksoulGoogleAdmob.loadAppOpen({
  adUnitId: 'ca-app-pub-3940256099942544/5662855259', // test app open
  isTesting: true,
});

await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.APP_OPEN_DISMISSED,
  () => console.log('App open cerrado')
);

// Llamar cuando tu lógica de “cold start / resume” lo permita
await BacksoulGoogleAdmob.showAppOpen();

Consulta la guía oficial de App open ads para límites de frecuencia y estados de la actividad (Android/iOS).

7. Nativo avanzado / Native Advanced (plantilla nativa)

Renderiza un bloque nativo (NativeAdView) encima del WebView, útil para feeds o home. marginBottom separa el anuncio de la barra de tabs / home indicator.

let hNative: { remove: () => Promise<void> } | undefined;

hNative = await BacksoulGoogleAdmob.addListener(
  BACKSOUL_ADMOB_EVENTS.NATIVE_ADVANCED_HEIGHT_CHANGED,
  (p) => {
    const px = Number(p.heightPx ?? 0);
    document.documentElement.style.setProperty('--native-ad-padding', `${px}px`);
  }
);

await BacksoulGoogleAdmob.showNativeAdvanced({
  // Test: Android 2247696110 · iOS 3986624511 (ver documentación Google “test ads”)
  adUnitId: 'ca-app-pub-3940256099942544/2247696110',
  marginBottom: 92,
});

// Al salir de la pantalla
await BacksoulGoogleAdmob.hideNativeAdvanced();
await hNative?.remove();

En plantilla Ionic, enlaza el padding al scroll, por ejemplo:
[style.--padding-bottom.px]="nativeAdPadding" y usa la variable CSS que actualizas arriba.

Referencia rápida de eventos (BACKSOUL_ADMOB_EVENTS)

| Constante | Evento emitido | |-----------|----------------| | BANNER_SIZE_CHANGED | Tamaño del banner (width, height). | | INTERSTITIAL_LOADED / INTERSTITIAL_FAILED_TO_LOAD / INTERSTITIAL_DISMISSED | Ciclo de vida del intersticial. | | REWARDED_* | Carga, fallo, recompensa (type, amount), cierre. | | REWARDED_INTERSTITIAL_* | Igual para intersticial bonificado. | | APP_OPEN_LOADED / APP_OPEN_FAILED_TO_LOAD / APP_OPEN_DISMISSED | App open. | | NATIVE_ADVANCED_HEIGHT_CHANGED | heightPx para reservar espacio en el WebView. |

Ejemplo mínimo anterior (solo banner)

await BacksoulGoogleAdmob.initialize({ testDeviceIds: ['DEVICE_HASH_ID'] });

await BacksoulGoogleAdmob.showBanner({
  adUnitId: 'ca-app-pub-xxx/yyy',
  position: 'BOTTOM_CENTER',
  margin: 92,
  adSize: 'ADAPTIVE_BANNER',
});

BacksoulGoogleAdmob.addListener(BACKSOUL_ADMOB_EVENTS.BANNER_SIZE_CHANGED, (p) => {
  console.log(p.width, p.height);
});

Repository

https://github.com/backsoul/capacitor-google-admob

Publicar en npm (mantenedores)

1. Inicia sesión: npm login (cuenta con permiso en la org @backsoul).
2. Desde la raíz del paquete: npm run build (o deja que prepublishOnly compile al publicar).
3. Comprueba el tarball: npm pack --dry-run.
4. Sube la versión: npm version patch|minor|major (opcional, actualiza package.json y crea tag git).
5. Publica: npm publish
   El campo publishConfig.access ya está en public para el scope @backsoul.

Tras publicar, en tu app: npm install @backsoul/capacitor-google-admob@latest y npx cap sync.

License

MIT