Getting Started

1. Install the package

   npm

   npm i @capgo/inappbrowser

   pnpm

   pnpm add @capgo/inappbrowser

   yarn

   yarn add @capgo/inappbrowser

   bun

   bun add @capgo/inappbrowser

2. Sync with native projects

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Usage

Import the plugin and use its methods to open web content:

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

// Open a URL
const openBrowser = async () => {
  await InAppBrowser.open({
    url: 'https://capgo.app',
    showTitle: true,
    toolbarColor: '#000000',
    showToolbar: true,
    showReload: true
  });
};

// Listen for URL changes
const setupListeners = async () => {
  // URL change event
  await InAppBrowser.addListener('urlChangeEvent', (event) => {
    console.log('URL changed to:', event.url);

    // Handle OAuth callbacks
    if (event.url.startsWith('myapp://oauth-callback')) {
      InAppBrowser.close();
      // Process OAuth response
    }
  });

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

  // Browser opened event
  await InAppBrowser.addListener('openEvent', () => {
    console.log('Browser opened');
  });
};

// Close the browser
const closeBrowser = async () => {
  await InAppBrowser.close();
};

// Reload current page
const reloadPage = async () => {
  await InAppBrowser.reload();
};

// Navigate to a new URL
const navigateTo = async (url: string) => {
  await InAppBrowser.openWebView({ url });
};

API Reference

open(options)

Opens a URL in the in-app browser.

interface OpenOptions {
  url: string;
  showTitle?: boolean;
  toolbarColor?: string;
  showToolbar?: boolean;
  showReload?: boolean;
  closeButtonText?: string;
  closeButtonColor?: string;
  presentationStyle?: 'fullscreen' | 'popover';
  transitionStyle?: 'coververtical' | 'crossdissolve' | 'fliphorizontal';
  enableBarsCollapsing?: boolean;
}

await InAppBrowser.open({
  url: 'https://example.com',
  showTitle: true,
  toolbarColor: '#1976d2',
  showToolbar: true
});

close()

Closes the in-app browser.

await InAppBrowser.close();

reload()

Reloads the current page.

await InAppBrowser.reload();

openWebView(options)

Navigates to a new URL in the already open browser.

interface OpenWebViewOptions {
  url: string;
}

await InAppBrowser.openWebView({
  url: 'https://new-page.com'
});

goBack()

Navigates back in the browser history.

await InAppBrowser.goBack();

goForward()

Navigates forward in the browser history.

await InAppBrowser.goForward();

Events

urlChangeEvent

Fired when the URL changes in the browser.

interface UrlChangeEvent {
  url: string;
}

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

closeEvent

Fired when the browser is closed.

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

openEvent

Fired when the browser is opened.

InAppBrowser.addListener('openEvent', () => {
  console.log('Browser opened');
});

Advanced Usage

OAuth Flow Implementation

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,
        showTitle: true,
        toolbarColor: '#1976d2'
      });
    });
  }

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

Custom Browser UI

const openCustomBrowser = async () => {
  await InAppBrowser.open({
    url: 'https://example.com',
    showTitle: true,
    toolbarColor: '#FF5722',
    showToolbar: true,
    showReload: true,
    closeButtonText: 'Done',
    closeButtonColor: '#FFFFFF',
    presentationStyle: 'fullscreen',
    transitionStyle: 'coververtical',
    enableBarsCollapsing: true
  });
};

Handling External Links

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,
        showTitle: true,
        showToolbar: 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));
  }
}

Best Practices

1. Always remove listeners

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

2. Handle browser states

   let browserOpen = false;
   
   InAppBrowser.addListener('openEvent', () => {
     browserOpen = true;
   });
   
   InAppBrowser.addListener('closeEvent', () => {
     browserOpen = false;
   });

3. Validate URLs before opening

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

4. Customize for platform

   import { Capacitor } from '@capacitor/core';
   
   const options = {
     url: 'https://example.com',
     showTitle: true,
     toolbarColor: Capacitor.getPlatform() === 'ios' ? '#007AFF' : '#1976D2'
   };

Platform Notes

iOS

• Uses SFSafariViewController
• Supports iOS 11.0+
• Respects Safe Area insets
• Supports custom presentation styles

Android

• Uses Chrome Custom Tabs
• Falls back to WebView if Chrome not available
• Supports Android 5.0 (API 21)+
• Toolbar customization supported

Web

• Opens in new browser tab/window
• Limited customization options
• No URL change events