Votre première application mobile

Ce guide vous explique comment exécuter une application de bureau Wails standard dans le simulateur iOS ou l’émulateur Android. Vous n’avez pas besoin de modifier votre code Go. Le même main.go permet de créer l’application pour toutes les cibles.

Temps nécessaire : 15–30 minutes (principalement pour l’installation de la chaîne d’outils lors de la première exécution)

Partir d’un projet de bureau

Si vous n’en avez pas encore, créez un nouveau projet :

wails3 init -n mymobileapp
cd mymobileapp

Vérifiez d’abord que l’application de bureau fonctionne :

wails3 dev

Une fois qu’elle est ouverte, quittez-la et poursuivez. Tout ce qui fonctionne sur ordinateur fonctionne également sur mobile : pour suivre ce guide, vous n’aurez à modifier ni main.go ni aucun code Go.

Choisir votre plateforme

wails3 task ios:run

wails3 task ios:logs:dev

wails3 task ios:xcode

sdkmanager "platform-tools" \
           "platforms;android-35" \
           "build-tools;35.0.0" \
           "ndk;26.3.11579264" \
           "emulator" \
           "system-images;android-35;google_apis;arm64-v8a"

avdmanager create avd \
  --name wails \
  --package "system-images;android-35;google_apis;arm64-v8a" \
  --device pixel_7

export ANDROID_HOME=~/android-sdk
export ANDROID_SDK_ROOT=~/android-sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin

# macOS
brew install openjdk@21
export JAVA_HOME=$(brew --prefix openjdk@21)

# Ubuntu/Debian
sudo apt install openjdk-21-jdk
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64

# Windows (scoop)
scoop install openjdk21

wails3 task android:run

wails3 task android:logs

Comprendre ce qui s’est passé

Votre main.go n’a absolument pas changé. Wails s’est chargé de tout :

• Système de build — le fichier Taskfile.yml de votre projet contient les tâches ios:* et android:* qui pilotent la chaîne d’outils propre à chaque plateforme.
• Compilation croisée de Go — GOOS=ios ou GOOS=android avec la valeur GOARCH et le sysroot appropriés.
• Hôte natif — un projet Xcode généré (iOS) ou un projet Gradle (Android) qui intègre votre code Go compilé et héberge la WebView.
• Mise à disposition des ressources — votre frontend/dist/ est intégré au binaire Go et servi dans le processus. Aucun serveur localhost n’est nécessaire.

Adaptez votre application aux appareils mobiles

Votre application fonctionne déjà, mais elle ressemble à une application de bureau sur l’écran d’un téléphone. Quelques petits changements feront toute la différence.

CSS adaptatif

Les écrans mobiles sont plus étroits et utilisent des modes de saisie différents. Dans frontend/public/style.css (ou son équivalent) :

/* Prevent horizontal scrolling */
body {
  overflow-x: hidden;
}

/* Touch-friendly tap targets */
button {
  min-height: 44px;
  min-width: 44px;
}

/* Respect the iOS safe area (notch, home indicator) */
body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

Détecter la plateforme en Go

Utilisez des balises de build pour ajouter un comportement propre à chaque plateforme sans encombrer le code partagé.

Créez mobile_ios.go pour le code réservé à iOS :

//go:build ios

package main

import "github.com/wailsapp/wails/v3/pkg/application"

func platformOptions() application.IOSOptions {
    return application.IOSOptions{
        DisableBounce: true,
    }
}

Créez mobile_android.go pour le code réservé à Android :

//go:build android

package main

import "github.com/wailsapp/wails/v3/pkg/application"

func platformOptions() application.AndroidOptions {
    return application.AndroidOptions{}
}

Créez mobile_desktop.go comme implémentation factice afin que le code partagé soit également compilé pour les plateformes de bureau :

//go:build !ios && !android

package main

type mobileOptions struct{}

func platformOptions() mobileOptions { return mobileOptions{} }

Détecter la plateforme en JavaScript et réserver l’interface mobile aux appareils mobiles

Les objets d’exécution IOS.* et Android.* n’existent que sur leur plateforme respective. Leur appel sur une plateforme de bureau déclenche une exception. La bonne approche, utilisée par Kitchen Sink, consiste à détecter la plateforme une seule fois et à masquer entièrement les contrôles réservés aux appareils mobiles :

// Detect platform from the bridge the host injects into the WebView
const platform = (() => {
  if (typeof window.wails?.platform === 'function') return window.wails.platform(); // Android
  if (window.webkit?.messageHandlers?.external) return 'ios';
  return 'desktop';
})();

const isIOS     = platform === 'ios';
const isAndroid = platform === 'android';
const isMobile  = isIOS || isAndroid;

// Hide any element marked as mobile-only
document.querySelectorAll('.mobile-only').forEach(el => {
  el.style.display = isMobile ? '' : 'none';
});

Puis, dans votre HTML :

<section class="mobile-only">
  <button id="btnHaptic">Haptic feedback</button>
</section>

Ainsi, les boutons réservés aux appareils mobiles ne sont jamais affichés sur les plateformes de bureau et vous n’avez pas besoin de protéger chaque appel par une vérification if (isMobile).

Côté Go, associez cette approche à une implémentation factice utilisant une balise de build, afin que les gestionnaires d’événements ne soient enregistrés que sur les plateformes qui en ont besoin :

//go:build !ios && !android

package main

import "github.com/wailsapp/wails/v3/pkg/application"

// No-op on desktop — mobile tabs are hidden in the frontend so these
// events are never emitted.
func registerNativeFeatures(app *application.App) {}

//go:build ios

package main

import "github.com/wailsapp/wails/v3/pkg/application"

func registerNativeFeatures(app *application.App) {
    app.Event.On("common:haptic", func(e *application.CustomEvent) {
        // only compiled and called on iOS
        application.IOS.Haptic("medium")
    })
    // ... other handlers
}

C’est exactement l’approche utilisée par Kitchen Sink : consultez native_features_stub.go, native_features_ios.go et native_features_android.go.

Ajouter un retour haptique (iOS)

import { IOS } from '@wailsio/runtime';

async function onButtonTap() {
  if (isIOS) {
    await IOS.Haptics.Impact({ style: 'medium' });
  }
  // ... rest of your handler
}

Ajouter des vibrations (Android)

import { Android } from '@wailsio/runtime';

async function onButtonTap() {
  if (isAndroid) {
    await Android.Haptics.Vibrate(50); // 50ms
  }
}

Compiler pour la production

wails3 task ios:package
wails3 task ios:deploy-simulator

wails3 task ios:package \
  IOS_PLATFORM=device \
  CODESIGN_IDENTITY="Apple Development: You (TEAMID)" \
  PROVISIONING_PROFILE=path/to/profile.mobileprovision

wails3 task ios:deploy-device   # installs via xcrun devicectl

wails3 task ios:package:ipa IOS_PLATFORM=device \
  CODESIGN_IDENTITY="..." \
  PROVISIONING_PROFILE=path/to/distribution.mobileprovision

wails3 task android:package
wails3 task android:deploy-emulator

ANDROID_KEYSTORE_FILE=/path/to/release.jks \
ANDROID_KEYSTORE_PASSWORD=yourpassword \
ANDROID_KEY_ALIAS=youralias \
ANDROID_KEY_PASSWORD=yourkeypassword \
  wails3 task android:package

wails3 task android:package:fat

Résolution des problèmes

Échec de wails3 task ios:run avec « no iOS SDKs found »

La version complète de Xcode doit être installée et sélectionnée :

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcode-select -p  # should print the Xcode path

Échec de wails3 task android:run avec « SDK not found »

Vérifiez que ANDROID_HOME est défini et exporté. Effectuez la vérification avec :

echo $ANDROID_HOME
ls $ANDROID_HOME/platform-tools/adb

Le simulateur ne démarre pas

Répertoriez les simulateurs disponibles et démarrez-en un manuellement :

xcrun simctl list devices available
xcrun simctl boot "iPhone 16"

chrome://inspect n’affiche aucune cible

La WebView doit être en mode débogage (le mode par défaut pour android:run). Vérifiez que vous exécutez un build de débogage et non un build de production. Vérifiez également que adb devices indique que l’émulateur est connecté.

Les marges de la zone sûre ne sont pas appliquées

Vérifiez que votre HTML inclut la balise meta viewport :

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

Explorer le Kitchen Sink

Une fois votre première application en cours d’exécution, l’exemple Kitchen Sink constitue le moyen le plus rapide de découvrir les autres possibilités. Il s’agit d’une application Wails complète qui s’exécute sur iOS, Android et les systèmes de bureau à partir d’une base de code unique. Elle couvre le retour haptique, la géolocalisation, la biométrie, les notifications locales, le stockage sécurisé et bien plus encore :

git clone https://github.com/wailsapp/wails.git
cd wails/v3/examples/mobile

wails3 task ios:run        # iOS Simulator
wails3 task android:run    # Android Emulator
wails3 task run            # Desktop

Parcourez le code source à l’adresse v3/examples/mobile. Les fichiers native_features_ios.go et native_features_android.go sont particulièrement utiles comme points de départ à copier-coller pour les fonctionnalités propres à chaque plateforme.

Et ensuite ?