Aplikasi Seluler Pertama Anda

Panduan ini menjalankan aplikasi desktop Wails standar di iOS Simulator atau Android Emulator. Anda tidak perlu mengubah kode Go. main.go yang sama digunakan untuk membangun aplikasi bagi semua target.

Waktu penyelesaian: 15–30 menit (sebagian besar waktunya digunakan untuk menginstal toolchain saat pertama kali dijalankan)

Mulai dari proyek desktop

Jika belum memilikinya, buat proyek baru:

wails3 init -n mymobileapp
cd mymobileapp

Pastikan terlebih dahulu bahwa aplikasi desktop berfungsi:

wails3 dev

Setelah terbuka, tutup aplikasi lalu lanjutkan. Semua yang berjalan di desktop juga berjalan di perangkat seluler—untuk panduan ini, Anda tidak perlu mengubah main.go ataupun kode Go apa pun.

Pilih platform Anda

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

Memahami apa yang terjadi

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

• Sistem build — Taskfile.yml dalam proyek Anda berisi tugas ios:* dan android:* yang menjalankan toolchain khusus platform.
• Kompilasi silang Go — GOOS=ios atau GOOS=android dengan GOARCH dan sysroot yang sesuai.
• Host native — proyek Xcode (iOS) atau proyek Gradle (Android) yang dihasilkan, yang menyematkan kode Go hasil kompilasi Anda dan menjadi host WebView.
• Penyajian aset — frontend/dist/ Anda disematkan dalam biner Go dan disajikan di dalam proses yang sama. Server localhost tidak diperlukan.

Sesuaikan aplikasi Anda untuk perangkat seluler

Aplikasi Anda sudah berfungsi, tetapi tampil seperti aplikasi desktop pada layar ponsel. Beberapa perubahan kecil dapat memberikan dampak besar.

CSS responsif

Layar perangkat seluler lebih sempit dan menggunakan pola input yang berbeda. Dalam frontend/public/style.css (atau yang 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);
}

Mendeteksi platform di Go

Gunakan tag build untuk menambahkan perilaku khusus platform tanpa memenuhi kode bersama dengan detail platform.

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 juga dapat dikompilasi di desktop:

//go:build !ios && !android

package main

type mobileOptions struct{}

func platformOptions() mobileOptions { return mobileOptions{} }

Mendeteksi platform di JavaScript dan membatasi UI khusus perangkat seluler

Objek runtime IOS.* dan Android.* hanya tersedia pada platformnya masing-masing. Memanggilnya di desktop akan menimbulkan error. Pola yang tepat—yang digunakan oleh Kitchen Sink—adalah mendeteksi platform satu kali dan menyembunyikan seluruh kontrol khusus perangkat seluler:

// 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, dalam HTML Anda:

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

Dengan cara ini, tombol khusus perangkat seluler tidak pernah dirender di desktop, dan Anda tidak perlu melindungi setiap pemanggilan dengan pemeriksaan if (isMobile).

Di sisi Go, padukan ini dengan stub bertag build agar event handler hanya didaftarkan pada platform yang memerlukannya:

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

Inilah pola persis yang digunakan oleh Kitchen Sink—lihat native_features_stub.go, native_features_ios.go, dan native_features_android.go.

Menambahkan umpan balik haptik (iOS)

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

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

Menambahkan getaran (Android)

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

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

Melakukan 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

Pemecahan masalah

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

Xcode versi lengkap harus diinstal 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 pesan “SDK not found”

Pastikan ANDROID_HOME telah ditetapkan dan diekspor. Verifikasikan dengan:

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

Simulator tidak dapat melakukan boot

Tampilkan daftar simulator yang tersedia dan lakukan boot pada salah satunya secara manual:

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

chrome://inspect tidak menampilkan target

WebView harus berada dalam mode debug (mode default untuk android:run). Pastikan Anda menjalankan build debug, bukan build produksi. Pastikan juga adb devices menampilkan emulator sebagai perangkat yang terhubung.

Inset area aman tidak diterapkan

Pastikan HTML Anda menyertakan tag meta viewport:

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

Jelajahi Kitchen Sink

Setelah aplikasi pertama Anda berjalan, contoh Kitchen Sink adalah cara tercepat untuk mempelajari berbagai kemungkinan lainnya. Contoh ini merupakan aplikasi Wails lengkap yang berjalan di iOS, Android, dan desktop dari satu basis kode, serta mencakup umpan balik haptik, geolokasi, biometrik, notifikasi lokal, penyimpanan aman, dan banyak lagi:

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

Telusuri kode sumber di v3/examples/mobile — file native_features_ios.go dan native_features_android.go sangat berguna sebagai titik awal yang dapat disalin dan ditempel untuk fitur khusus platform.

Langkah berikutnya