Erste Schritte

1. Installieren Sie das Paket

   npm

   npm i @capgo/inappbrowser

   pnpm

   pnpm add @capgo/inappbrowser

   yarn

   yarn add @capgo/inappbrowser

   bun

   bun add @capgo/inappbrowser

2. Mit nativen Projekten synchronisieren

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Verwendung

Importieren Sie das Plugin und verwenden Sie seine zwei Haupteinstiegspunkte:

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

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

// 2) Vollständige WebView mit Navigation, Headern, Teilen, Messaging usw.
const openWebView = async () => {
  await InAppBrowser.openWebView({
    url: 'https://capgo.app',
    title: 'Capgo',
    toolbarType: ToolBarType.NAVIGATION,
    backgroundColor: BackgroundColor.BLACK,
    activeNativeNavigationForWebview: true,
    showReloadButton: true,
    shareSubject: 'Schauen Sie sich diese Seite an',
    shareDisclaimer: {
      title: 'Haftungsausschluss',
      message: 'Sie sind dabei, Inhalte zu teilen',
      confirmBtn: 'Fortfahren',
      cancelBtn: 'Abbrechen',
    },
  });
};

// Nachrichtenaustausch zwischen App und geöffneter WebView
const setupListeners = async () => {
  await InAppBrowser.addListener('urlChangeEvent', (event) => {
    console.log('URL geändert zu:', event.url);
  });

  await InAppBrowser.addListener('messageFromWebview', (event) => {
    console.log('Nachricht vom Web:', event.detail);
  });

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

// Daten an die WebView senden
const sendData = async () => {
  await InAppBrowser.postMessage({ detail: { action: 'refresh-profile' } });
};

// Hilfsfunktionen zum Schließen und Neuladen
const closeBrowser = () => InAppBrowser.close();
const reloadPage = () => InAppBrowser.reload();

API-Referenz

open(options: OpenOptions)

Öffnet eine URL in einem Custom Tab / SFSafariViewController.

interface OpenOptions {
  /** Ziel-URL zum Laden */
  url: string;
  /** Nach Abschluss des Seitenladens anzeigen */
  isPresentAfterPageLoad?: boolean;
  /** Verhindern, dass Deep Links externe Apps öffnen */
  preventDeeplink?: boolean;
}

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

openWebView(options: OpenWebViewOptions)

Lädt eine vollständig ausgestattete WebView mit Navigations-UI, Headern, Anmeldeinformationen, Skripting und Messaging.

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,
});

ToolBarType Werte: activity (Schließen + Teilen), compact (nur Schließen), navigation (Zurück/Vorwärts + Schließen), blank (keine Toolbar). BackgroundColor Werte: white oder black.

close(options?)

Schließt die WebView/den Custom Tab.

Optionen:

• isAnimated?: boolean - Ob die Schließaktion animiert werden soll

reload()

Lädt die aktuelle WebView-Seite neu.

goBack()

Geht in der WebView-Historie zurück und gibt { canGoBack: boolean } zurück.

setUrl({ url: string })

Ersetzt die aktuelle WebView-URL.

executeScript({ code: string })

Injiziert JavaScript in die WebView.

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

Sendet Daten von der nativen App an die WebView (empfangen in JS über window.addEventListener('messageFromNative', ...)).

getCookies({ url, includeHttpOnly? })

Gibt Cookies für die URL zurück.

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

Hilfsfunktionen zur Verwaltung von Cookies und Cache.

updateDimensions(options: DimensionOptions)

Ändert WebView-Größe/-Position zur Laufzeit (width, height, x, y).

removeAllListeners()

Entfernt alle Listener für das Plugin.

Ereignisse

urlChangeEvent

Wird ausgelöst, wenn sich die URL im Browser ändert.

interface UrlChangeEvent {
  url: string;
}

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

messageFromWebview

Wird ausgelöst, wenn window.mobileApp.postMessage(...) innerhalb der WebView aufgerufen wird.

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

closeEvent

Wird ausgelöst, wenn der Browser geschlossen wird.

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

buttonNearDoneClick

Wird ausgelöst, wenn die benutzerdefinierte Schaltfläche, die mit buttonNearDone hinzugefügt wurde, gedrückt wird.

InAppBrowser.addListener('buttonNearDoneClick', (event) => {
  console.log('Schaltfläche neben Fertig getippt', event);
});

confirmBtnClicked

Wird ausgelöst, wenn ein Bestätigungsdialog (Haftungsausschluss oder Schließen-Modal) akzeptiert wird.

InAppBrowser.addListener('confirmBtnClicked', (event) => {
  console.log('Bestätigung akzeptiert, aktuelle URL:', event.url);
});

browserPageLoaded / pageLoadError

Lebenszyklusereignisse für erfolgreichen oder fehlgeschlagenen WebView-Ladevorgang.

InAppBrowser.addListener('browserPageLoaded', () => console.log('Seite geladen'));
InAppBrowser.addListener('pageLoadError', () => console.log('Seite konnte nicht geladen werden'));

Erweiterte Verwendung

OAuth-Flow-Implementierung

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

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

  async authenticate(authUrl: string, redirectUri: string) {
    return new Promise<string>((resolve, reject) => {
      // Auf URL-Änderungen hören
      const urlListener = InAppBrowser.addListener('urlChangeEvent', (event) => {
        if (event.url.startsWith(redirectUri)) {
          // OAuth-Code/Token aus URL extrahieren
          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 fehlgeschlagen'));
          }
        }
      });

      this.listeners.push(urlListener);

      // OAuth-Anbieter öffnen
      InAppBrowser.open({
        url: authUrl,
        preventDeeplink: true,
      });
    });
  }

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

Benutzerdefinierte Browser-UI

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

Umgang mit externen Links

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

export class LinkHandler {
  async openExternalLink(url: string) {
    // Prüfen, ob URL im Browser geöffnet werden soll
    if (this.shouldOpenInBrowser(url)) {
      await InAppBrowser.open({
        url,
        preventDeeplink: true,
      });
    } else {
      // Intern behandeln
      window.location.href = url;
    }
  }

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

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

Best Practices

1. Listener immer entfernen

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

2. Browser-Zustände handhaben

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

3. URLs vor dem Öffnen validieren

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

4. Für Plattform anpassen

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

Plattform-Hinweise

iOS

• Verwendet SFSafariViewController
• Unterstützt iOS 11.0+
• Respektiert Safe Area Insets
• Unterstützt benutzerdefinierte Präsentationsstile

Android

• Verwendet Chrome Custom Tabs
• Fällt auf WebView zurück, wenn Chrome nicht verfügbar ist
• Unterstützt Android 5.0 (API 21)+
• Toolbar-Anpassung über toolbarType, toolbarColor, buttonNearDone usw. unterstützt

Web

• Öffnet in neuem Browser-Tab/-Fenster
• Eingeschränkte Anpassungsoptionen
• Keine URL-Änderungsereignisse