Pular para o conteúdo
Wails Blog

Android

Este conteúdo não está disponível em sua língua ainda.

Wails v3 applications run on Android as native apps: an Android WebView renders the frontend, assets are served in-process through a WebViewAssetLoader backed by the Go asset server (no localhost server, no open ports), and the standard @wailsio/runtime works unchanged — service bindings, events, dialogs and the clipboard route through the Go message processor.

The same main.go builds for desktop and Android. The Go code is compiled as a C shared library (libwails.so, GOOS=android + the NDK toolchain) and loaded by a small Java host. Android-specific behaviour lives in per-platform Go files guarded by //go:build android.

Requirements

Section titled “Requirements”
  • The Android SDK with platform-tools, an SDK platform (API 34), build-tools and the NDK (26.3.x) — wails3 doctor shows what it finds
  • A JDK (e.g. OpenJDK 21) for Gradle; set JAVA_HOME if java is not on your PATH
  • Go 1.24+ and npm
  • ANDROID_HOME (or ANDROID_SDK_ROOT) pointing at the SDK

Install the SDK pieces with the command-line tools:

Terminal window
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0" \
           "ndk;26.3.11579264" "emulator" \
           "system-images;android-34;google_apis;arm64-v8a"
avdmanager create avd --name wails \
           --package "system-images;android-34;google_apis;arm64-v8a" \
           --device pixel_7

Running on the Emulator

Section titled “Running on the Emulator”

From your project directory:

Terminal window
wails3 task android:run

This boots an emulator if none is running, generates the bindings, builds the frontend, compiles your Go code to libwails.so for the emulator’s ABI, assembles a debug APK with Gradle, then installs and launches it.

Useful companions:

Terminal window
wails3 task android:logs    # stream the app's logcat output

In debug builds the WebView is inspectable from Chrome at chrome://inspect.

Packaging

Section titled “Packaging”
Terminal window
wails3 task android:package             # production release APK
wails3 task android:deploy-emulator     # install + launch it

Production builds use -tags production,android, are stripped, and compile out the framework’s internal diagnostics. wails3 task android:package:fat builds both arm64-v8a and x86_64 into a single APK.

Signing & release builds

Section titled “Signing & release builds”

Without a keystore, release builds are signed with the Android debug keystore so they install for testing. To sign with your own keystore, set:

Terminal window
ANDROID_KEYSTORE_FILE=/path/to/release.jks \
ANDROID_KEYSTORE_PASSWORD=... \
ANDROID_KEY_ALIAS=... \
ANDROID_KEY_PASSWORD=... \
  wails3 task android:package

Configuration

Section titled “Configuration”

The frontend drives Android features at runtime through the Android runtime object: Android.Haptics.Vibrate(durationMs), Android.Device.Info(), Android.Toast.Show(message). The package name is controlled by APP_ID in the build tasks.

What works, what doesn’t

Section titled “What works, what doesn’t”
AreaStatus
WebView + in-process assets (WebViewAssetLoader)✅
Service bindings, events (both directions)✅
Message dialogs✅ AlertDialog with button callbacks
Open file / files dialogs✅ Storage Access Framework (files imported as cache copies)
Open directory / save file dialogs❌ Return an error — write inside the app sandbox instead
Clipboard✅ ClipboardManager
Screens API✅ WindowMetrics incl. system-bar work area
Lifecycle events (events.Android.*)✅
Haptics, device info, toast✅ Android.* runtime API
Window geometry, menus, system trayIntentional no-ops
Multiple windowsOnly the first window is displayed

Porting notes

Section titled “Porting notes”
  • Desktop code compiles unchanged under GOOS=android; geometry/menu/tray calls become no-ops because Android apps are fullscreen.
  • android implies the linux build tag (Android is a Linux kernel): desktop-Linux-only files need //go:build linux && !android, and at runtime runtime.GOOS is "android".
  • Replace save-file and choose-directory dialogs with writes into the app sandbox plus an intent share flow. Open-file dialogs work and import the chosen documents as cache-directory copies, so you get real filesystem paths.
  • A real app is always built with CGO_ENABLED=1 and the NDK; the non-cgo path exists only so tooling such as wails3 generate bindings can load the package.
  • Design the frontend responsively; the Screens work area excludes the status and navigation bars.