Passer au contenu
Capgo - Live Updates for Capacitor Apps Capgo

Commencer

  1. Installer the package

    Fenêtre de terminal
    npm i @capgo/home-indicator

  2. Synchroniser with Natif projects

    Fenêtre de terminal
    npx cap sync

  3. Configure the plugin

    Hide Home Indicator:

    import { HomeIndicator } from '@capgo/home-indicator';
    

    // Hide the home indicator
    await HomeIndicator.hide();

    Show Home Indicator:

    // Show the home indicator
    await HomeIndicator.show();
    

    // Check visibility status
    const { hidden } = await HomeIndicator.isHidden();
    console.log('Is hidden:', hidden);

    No additional Configuration required. The plugin only works on iOS Appareils with a Accueil indicator (iPhone X and later).

  4. Auto-hide Configuration

    import { HomeIndicator } from '@capgo/home-indicator';
    

    // Configure auto-hide behavior
    await HomeIndicator.setAutoHidden({
      autoHidden: true // Enable auto-hide
    });
    

    // The home indicator will automatically hide after a few seconds
    // and reappear when the user touches the screen

  5. Advanced Utilisation

    import { HomeIndicator } from '@capgo/home-indicator';
    import { App } from '@capacitor/app';
    

    export class ImmersiveMode {
      private isImmersive = false;
    

      async enterImmersiveMode() {
        this.isImmersive = true;
    

        // Hide home indicator
        await HomeIndicator.hide();
    

        // Enable auto-hide for better UX
        await HomeIndicator.setAutoHidden({ autoHidden: true });
    

        // Hide status bar for full immersion
        // StatusBar.hide(); // If using @capacitor/status-bar
      }
    

      async exitImmersiveMode() {
        this.isImmersive = false;
    

        // Show home indicator
        await HomeIndicator.show();
    

        // Disable auto-hide
        await HomeIndicator.setAutoHidden({ autoHidden: false });
    

        // Show status bar
        // StatusBar.show(); // If using @capacitor/status-bar
      }
    

      async toggleImmersiveMode() {
        const { hidden } = await HomeIndicator.isHidden();
    

        if (hidden) {
          await this.exitImmersiveMode();
        } else {
          await this.enterImmersiveMode();
        }
      }
    

      setupAppLifecycle() {
        // Handle app state changes
        App.addListener('appStateChange', async ({ isActive }) => {
          if (!isActive && this.isImmersive) {
            // App went to background, might want to show indicator
            await HomeIndicator.show();
          } else if (isActive && this.isImmersive) {
            // App came to foreground, restore immersive mode
            await HomeIndicator.hide();
          }
        });
      }
    }

API Référence

Section titled “API Référence”

Methods

Section titled “Methods”

hide()

Section titled “hide()”

Hide the Accueil indicator.

Returns: Promise<void>

show()

Section titled “show()”

Show the Accueil indicator.

Returns: Promise<void>

isHidden()

Section titled “isHidden()”

Vérifier if the Accueil indicator is currently hidden.

Returns: Promise<{ hidden: boolean }>

setAutoHidden(options: { autoHidden: boolean })

Section titled “setAutoHidden(options: { autoHidden: boolean })”

Configure auto-hide behavior for the Accueil indicator.

Parameters:

  • options.autoHidden: boolean - Enable or disable auto-hide

Returns: Promise<void>

Interfaces

Section titled “Interfaces”
interface AutoHiddenOptions {
  autoHidden: boolean;
}


interface HiddenResult {
  hidden: boolean;
}

Platform Notes

Section titled “Platform Notes”

iOS

Section titled “iOS”
  • Only works on Appareils with Accueil indicator (iPhone X and later)
  • Requires iOS 11.0 or later
  • Auto-hide makes the indicator translucent and hides after inactivity
  • The indicator reappears when Utilisateurs swipe from the bottom

Android

Section titled “Android”
  • This plugin has no effect on Android
  • Android uses different navigation gestures/buttons

Common Use Cases

Section titled “Common Use Cases”
  1. Games: Full-screen gaming without distractions
  2. Video Players: Immersive video playback
  3. Photo Viewers: Full-screen photo galleries
  4. Presentations: Distraction-free presentations
  5. Kiosk Apps: Public display applications

Best Practices

Section titled “Best Practices”

  1. Utilisateur Control: Always provide a way to exit immersive mode

    // Add a gesture or button to toggle immersive mode
    const toggleButton = document.getElementById('toggle-immersive');
    toggleButton.addEventListener('click', () => {
      immersiveMode.toggleImmersiveMode();
    });

  2. Auto-Hide for Games: Use auto-hide for better gaming experience

    // For games, auto-hide provides the best balance
    await HomeIndicator.setAutoHidden({ autoHidden: true });

  3. Respect System Gestures: Don’t interfere with system navigation

  4. Enregistrer State: Remember Utilisateur’s preference for immersive mode

Dépannage

Section titled “Dépannage”

Home indicator not hiding:

  • Verify the Appareil has a Accueil indicator (iPhone X+)
  • Vérifier iOS Version is 11.0 or higher
  • Ensure the Application has focus

Auto-hide not working:

  • Auto-hide requires Utilisateur interaction to activate
  • The indicator becomes translucent, not completely hidden

Indicator reappears unexpectedly:

  • This is normal iOS behavior for system gestures
  • Use auto-hide for less intrusive behavior