Aplikasi Mobile Pertama Anda

Panduan ini mengambil aplikasi Wails desktop standar dan menjalankannya di iOS Simulator atau Android Emulator. Anda tidak perlu mengubah kode Go. main.go yang sama di-build untuk semua target.

Waktu penyelesaian: 15–30 menit (sebagian besar adalah instalasi toolchain pada run pertama)

Mulai dari proyek desktop

Jika belum punya, buat proyek baru:

wails3 init -n mymobileapp
cd mymobileapp

Konfirmasi aplikasi desktop bekerja terlebih dahulu:

wails3 dev

Setelah terbuka, tutup dan lanjutkan. Semua yang berjalan di desktop juga berjalan di mobile — Anda tidak perlu menyentuh main.go atau kode Go apa pun untuk panduan ini.

Pilih platform Anda

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

wails3 task ios:run

wails3 task ios:logs:dev

wails3 task ios:xcode

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

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

Memahami apa yang terjadi

main.go Anda tidak berubah sama sekali. Wails menangani semuanya:

• Build system — Taskfile.yml di proyek Anda berisi task ios:* dan android:* yang menggerakkan toolchain spesifik platform.
• Cross-compilation Go — GOOS=ios atau GOOS=android dengan GOARCH dan sysroot yang sesuai.
• Host native — proyek Xcode (iOS) atau Gradle (Android) yang di-generate yang menyematkan kode Go terkompilasi dan menghost WebView.
• Penyajian aset — frontend/dist/ disematkan ke binary Go dan disajikan in-process. Tidak perlu server localhost.

Buat aplikasi Anda mobile-aware

Aplikasi Anda sudah bekerja, tetapi terlihat seperti aplikasi desktop di layar ponsel. Beberapa perubahan kecil membuat perbedaan besar.

CSS Responsif

Layar mobile lebih sempit dan menggunakan pola input berbeda. Di frontend/public/style.css (atau setara):

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

Deteksi platform di Go

Gunakan build tag untuk menambahkan perilaku spesifik platform tanpa mengacaukan kode bersama.

Buat mobile_ios.go untuk kode khusus iOS:

//go:build ios

package main

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

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

Buat mobile_android.go untuk kode khusus Android:

//go:build android

package main

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

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

Buat mobile_desktop.go sebagai stub agar kode bersama dikompilasi di desktop juga:

//go:build !ios && !android

package main

type mobileOptions struct{}

func platformOptions() mobileOptions { return mobileOptions{} }

Deteksi platform di JavaScript dan gate UI khusus mobile

Objek runtime IOS.* dan Android.* hanya ada di platform masing-masing. Memanggilnya di desktop akan throw. Pola yang benar — digunakan oleh Kitchen Sink — adalah mendeteksi platform sekali dan menyembunyikan kontrol khusus mobile sepenuhnya:

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

Kemudian di HTML Anda:

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

Dengan cara ini tombol khusus mobile tidak pernah dirender di desktop, dan Anda tidak perlu guard setiap panggilan individual dengan pengecekan if (isMobile).

Di sisi Go, pasangkan ini dengan stub build-tag agar event handler hanya didaftarkan di platform yang membutuhkannya:

//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
}

Ini adalah pola persis yang digunakan Kitchen Sink — lihat native_features_stub.go, native_features_ios.go, dan native_features_android.go.

Tambahkan haptic feedback (iOS)

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

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

Tambahkan vibrasi (Android)

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

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

Build untuk produksi

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

Troubleshooting

wails3 task ios:run gagal dengan “no iOS SDKs found”

Xcode lengkap harus terinstal dan dipilih:

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

wails3 task android:run gagal dengan “SDK not found”

Pastikan ANDROID_HOME diatur dan diekspor. Verifikasi dengan:

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

Simulator tidak boot

Daftar simulator yang tersedia dan boot satu secara manual:

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

chrome://inspect tidak menampilkan target

WebView harus dalam mode debug (default untuk android:run). Pastikan Anda menjalankan debug build, bukan production. Juga konfirmasi adb devices menampilkan emulator terhubung.

Safe area inset tidak diterapkan

Pastikan HTML Anda menyertakan meta tag viewport:

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

Jelajahi Kitchen Sink

Setelah aplikasi pertama berjalan, contoh Kitchen Sink adalah cara tercepat mempelajari apa lagi yang mungkin. Ini adalah aplikasi Wails lengkap yang berjalan di iOS, Android, dan desktop dari satu codebase, mencakup haptics, geolocation, biometrics, notifikasi lokal, secure storage, dan lainnya:

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

Jelajahi source di v3/examples/mobile — file native_features_ios.go dan native_features_android.go sangat berguna sebagai starting point copy-paste untuk fitur spesifik platform.

Apa selanjutnya