Empezando

1. Instalar el paquete

   npm

   npm i @capgo/inappbrowser

   pnpm

   pnpm add @capgo/inappbrowser

   yarn

   yarn add @capgo/inappbrowser

   bun

   bun add @capgo/inappbrowser

2. Sincronización con proyectos nativos

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Uso

Importe el complemento y utilice sus dos puntos de entrada principales:

import { InAppBrowser, ToolBarType, BackgroundColor } from '@capgo/inappbrowser';

// 1) Simple custom tab / SFSafariViewController
const openExternal = async () => {
  await InAppBrowser.open({
    url: 'https://capgo.app',
    isPresentAfterPageLoad: true,
    preventDeeplink: false,
  });
};

// 2) Full WebView with navigation, headers, share, messaging, etc.
const openWebView = async () => {
  await InAppBrowser.openWebView({
    url: 'https://capgo.app',
    title: 'Capgo',
    toolbarType: ToolBarType.NAVIGATION,
    backgroundColor: BackgroundColor.BLACK,
    activeNativeNavigationForWebview: true,
    showReloadButton: true,
    shareSubject: 'Check this page',
    shareDisclaimer: {
      title: 'Disclaimer',
      message: 'You are about to share content',
      confirmBtn: 'Continue',
      cancelBtn: 'Cancel',
    },
  });
};

// Messaging between app and the opened WebView
const setupListeners = async () => {
  await InAppBrowser.addListener('urlChangeEvent', (event) => {
    console.log('URL changed to:', event.url);
  });

  await InAppBrowser.addListener('messageFromWebview', (event) => {
    console.log('Message from web:', event.detail);
  });

  await InAppBrowser.addListener('closeEvent', () => {
    console.log('WebView closed');
  });
};

// Send data to the WebView
const sendData = async () => {
  await InAppBrowser.postMessage({ detail: { action: 'refresh-profile' } });
};

// Close and reload helpers
const closeBrowser = () => InAppBrowser.close();
const reloadPage = () => InAppBrowser.reload();

API Referencia

abierto(opciones: OpenOptions)

Abre una URL en una pestaña personalizada/SFSafariViewController.

interface OpenOptions {
  /** Target URL to load */
  url: string;
  /** Present after the page finishes loading */
  isPresentAfterPageLoad?: boolean;
  /** Prevent deep links from opening external apps */
  preventDeeplink?: boolean;
}

await InAppBrowser.open({ url: 'https://example.com', preventDeeplink: true });

openWebView (opciones: OpenWebViewOptions)

Carga un WebView con todas las funciones con interfaz de usuario de navegación, encabezados, credenciales, secuencias de comandos y mensajes.

interface OpenWebViewOptions {
  url: string;
  headers?: Record<string, string>;
  credentials?: { username: string; password: string };
  materialPicker?: boolean;
  shareDisclaimer?: {
    title: string;
    message: string;
    confirmBtn: string;
    cancelBtn: string;
  };
  toolbarType?: ToolBarType;
  shareSubject?: string;
  title?: string;
  backgroundColor?: BackgroundColor;
  activeNativeNavigationForWebview?: boolean;
  disableGoBackOnNativeApplication?: boolean;
  isPresentAfterPageLoad?: boolean;
  isInspectable?: boolean;
  isAnimated?: boolean;
  showReloadButton?: boolean;
  closeModal?: boolean;
  closeModalTitle?: string;
  closeModalDescription?: string;
  closeModalOk?: string;
  closeModalCancel?: string;
  visibleTitle?: boolean;
  toolbarColor?: string;
  toolbarTextColor?: string;
  showArrow?: boolean;
  ignoreUntrustedSSLError?: boolean;
  preShowScript?: string;
  preShowScriptInjectionTime?: 'documentStart' | 'pageLoad';
  proxyRequests?: string;
  buttonNearDone?: {
    ios: { iconType: 'sf-symbol' | 'asset'; icon: string };
    android: { iconType: 'asset' | 'vector'; icon: string; width?: number; height?: number };
  };
  textZoom?: number;
  preventDeeplink?: boolean;
  authorizedAppLinks?: string[];
  enabledSafeBottomMargin?: boolean;
  useTopInset?: boolean;
  enableGooglePaySupport?: boolean;
  blockedHosts?: string[];
  width?: number;
  height?: number;
  x?: number;
  y?: number;
}

await InAppBrowser.openWebView({
  url: 'https://new-page.com',
  toolbarType: ToolBarType.NAVIGATION,
  showReloadButton: true,
});

Valores de ToolBarType: activity (cerrar + compartir), compact (solo cerrar), navigation (atrás/adelante + cerrar), blank (sin barra de herramientas). Valores BackgroundColor: white o black.

cerrar(¿opciones?)

Cierra la pestaña WebView/personalizado.

Opciones:

• isAnimated?: boolean - Si se anima la acción de cierre

recargar()

Vuelve a cargar la página WebView actual.

volver()

Vuelve al historial de WebView y devuelve { canGoBack: boolean }.

setUrl({ url: string })

Reemplaza la URL de WebView actual.

executeScript({ code: string })

Inyecta JavaScript en WebView.

postMessage({ detail: Record<string, any> })

Envía datos desde la aplicación nativa a WebView (recibirlos en JS a través de window.addEventListener('messageFromNative', ...)).

getCookies({ url, includeHttpOnly? })

Devuelve cookies para la URL.

clearCookies({ url }) / clearAllCookies() / clearCache()

Ayudantes de gestión de cookies y caché.

actualizarDimensiones(opciones: DimensionOptions)

Cambie el tamaño/posición de WebView en tiempo de ejecución (width, height, x, y).

eliminarTodos los oyentes()

Anule el registro de todos los oyentes del complemento.

Eventos

Evento de cambio de URL

Se activa cuando la URL cambia en el navegador.

interface UrlChangeEvent {
  url: string;
}

InAppBrowser.addListener('urlChangeEvent', (event) => {
  console.log('New URL:', event.url);
});

messageFromWebview

Se activa cuando se llama a window.mobileApp.postMessage(...) dentro de WebView.

InAppBrowser.addListener('messageFromWebview', (event) => {
  console.log('Payload from web:', event.detail);
});

cerrarEvento

Se activa cuando se cierra el navegador.

InAppBrowser.addListener('closeEvent', () => {
  console.log('Browser closed');
});

botónCerca de hechoClic

Se activa cuando se presiona el botón personalizado agregado con buttonNearDone.

InAppBrowser.addListener('buttonNearDoneClick', (event) => {
  console.log('Button near done tapped', event);
});

confirmarBtnClicked

Se activa cuando se acepta un cuadro de diálogo de confirmación (exención de responsabilidad o modo de cierre).

InAppBrowser.addListener('confirmBtnClicked', (event) => {
  console.log('Confirm accepted, current URL:', event.url);
});

navegadorPageLoaded / pageLoadError

Eventos del ciclo de vida para el éxito o el fracaso de la carga de WebView.

InAppBrowser.addListener('browserPageLoaded', () => console.log('Page loaded'));
InAppBrowser.addListener('pageLoadError', () => console.log('Page failed to load'));

Uso avanzado

OAuth Implementación de flujo

import { InAppBrowser } from '@capgo/inappbrowser';

export class OAuthService {
  private listeners: any[] = [];

  async authenticate(authUrl: string, redirectUri: string) {
    return new Promise<string>((resolve, reject) => {
      // Listen for URL changes
      const urlListener = InAppBrowser.addListener('urlChangeEvent', (event) => {
        if (event.url.startsWith(redirectUri)) {
          // Extract OAuth code/token from URL
          const url = new URL(event.url);
          const code = url.searchParams.get('code');

          if (code) {
            InAppBrowser.close();
            resolve(code);
          } else {
            const error = url.searchParams.get('error');
            reject(new Error(error || 'OAuth failed'));
          }
        }
      });

      this.listeners.push(urlListener);

      // Open OAuth provider
      InAppBrowser.open({
        url: authUrl,
        preventDeeplink: true,
      });
    });
  }

  cleanup() {
    this.listeners.forEach(listener => listener.remove());
    this.listeners = [];
  }
}

Interfaz de usuario personalizada del navegador

const openCustomBrowser = async () => {
  await InAppBrowser.open({
    url: 'https://example.com',
    isPresentAfterPageLoad: true,
    preventDeeplink: false,
  });
};

Manejo de enlaces externos

import { InAppBrowser } from '@capgo/inappbrowser';

export class LinkHandler {
  async openExternalLink(url: string) {
    // Check if URL should open in browser
    if (this.shouldOpenInBrowser(url)) {
      await InAppBrowser.open({
        url,
        preventDeeplink: true,
      });
    } else {
      // Handle internally
      window.location.href = url;
    }
  }

  private shouldOpenInBrowser(url: string): boolean {
    // External domains
    const externalDomains = ['youtube.com', 'twitter.com', 'facebook.com'];
    const urlDomain = new URL(url).hostname;

    return externalDomains.some(domain => urlDomain.includes(domain));
  }
}

Mejores prácticas

1. Eliminar siempre a los oyentes

   const listener = await InAppBrowser.addListener('urlChangeEvent', handler);
   // When done
   listener.remove();

2. Manejar estados del navegador

   let browserOpen = false;
   
   const launch = async () => {
     browserOpen = true;
     await InAppBrowser.openWebView({ url: 'https://example.com' });
   };
   
   InAppBrowser.addListener('closeEvent', () => {
     browserOpen = false;
   });

3. Valide las URL antes de abrirlas

   const isValidUrl = (url: string): boolean => {
     try {
       new URL(url);
       return true;
     } catch {
       return false;
     }
   };
   
   if (isValidUrl(url)) {
     await InAppBrowser.open({ url });
   }

4. Personalizar según la plataforma

   import { Capacitor } from '@capacitor/core';
   
   const options = {
     url: 'https://example.com',
     preventDeeplink: Capacitor.getPlatform() === 'ios',
   };

Notas de plataforma

iOS

• Utiliza SFSafariViewController
• Soporta iOS 11.0+
• Respeta las inserciones del Área Segura
• Admite estilos de presentación personalizados

Android

• Utiliza pestañas personalizadas de Chrome
• Vuelve a WebView si Chrome no está disponible
• Soporta Android 5.0 (API 21)+
• Personalización de la barra de herramientas compatible a través de toolbarType, toolbarColor, buttonNearDone, etc.

Web

• Se abre en una nueva pestaña/ventana del navegador
• Opciones de personalización limitadas
• No hay eventos de cambio de URL