Commencer

1. Installez le package

   npm

   npm i @capgo/inappbrowser

   pnpm

   pnpm add @capgo/inappbrowser

   yarn

   yarn add @capgo/inappbrowser

   bun

   bun add @capgo/inappbrowser

2. Synchronisation avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Utilisation

Importez le plugin et utilisez ses deux points d’entrée principaux :

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 Référence

ouvert(options : OpenOptions)

Ouvre une URL dans un onglet personnalisé / 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 (options : OpenWebViewOptions)

Charge une WebView complète avec une interface utilisateur de navigation, des en-têtes, des informations d’identification, des scripts et une messagerie.

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

Valeurs ToolBarType : activity (fermer + partager), compact (fermer uniquement), navigation (avant/arrière + fermer), blank (pas de barre d’outils). Valeurs BackgroundColor : white ou black.

close(options?)

Ferme l’onglet WebView/personnalisé.

Options:

• isAnimated?: boolean - S’il faut animer l’action de clôture

recharger()

Recharge la page WebView actuelle.

goBack()

Revient dans l’historique WebView et renvoie { canGoBack: boolean }.

setUrl({ url: string })

Remplace l’URL WebView actuelle.

executeScript({ code: string })

Injecte JavaScript dans WebView.

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

Envoie les données de l’application native au WebView (recevoir en JS via window.addEventListener('messageFromNative', ...)).

getCookies({ url, includeHttpOnly? })

Renvoie les cookies pour l’URL.

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

Aides à la gestion des cookies et du cache.

updateDimensions(options : DimensionOptions)

Modifiez la taille/la position de WebView au moment de l’exécution (width, height, x, y).

supprimerAllListeners()

Désinscrivez tous les auditeurs du plugin.

Événements

urlChangeEvent

Déclenché lorsque l’URL change dans le navigateur.

interface UrlChangeEvent {
  url: string;
}

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

messageFromWebview

Déclenché lorsque window.mobileApp.postMessage(...) est appelé dans WebView.

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

fermer l’événement

Lancé lorsque le navigateur est fermé.

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

buttonNearDoneClick

Déclenché lorsque le bouton personnalisé ajouté avec buttonNearDone est enfoncé.

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

confirmBtnClicked

Déclenché lorsqu’une boîte de dialogue de confirmation (avertissement ou fermeture modale) est acceptée.

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

navigateurPageLoaded / pageLoadError

Événements de cycle de vie pour le succès ou l’échec du chargement de WebView.

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

Utilisation avancée

OAuth Implémentation du flux

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 = [];
  }
}

Interface utilisateur du navigateur personnalisé

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

Gestion des liens externes

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

## meilleures pratiques

1. Toujours supprimer les auditeurs

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

2. Gérer les états du navigateur

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

3. Valider les URL avant d’ouvrir

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

4. Personnaliser pour la plateforme

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

## Remarques sur la plate-forme

iOS

• Uses SFSafariViewController
• Prend en charge iOS 11.0+
• Respecte les encarts de zone de sécurité
• Prend en charge les styles de présentation personnalisés

Android

• Utilise les onglets personnalisés Chrome
• Revient à WebView si Chrome n’est pas disponible
• Prend en charge Android 5.0 (API 21)+
• Personnalisation de la barre d’outils prise en charge via toolbarType, toolbarColor, buttonNearDone, etc.

###Web

• S’ouvre dans un nouvel onglet/fenêtre du navigateur
• Options de personnalisation limitées
• Aucun événement de changement d’URL