iOS Physical Device Guide
Hướng dẫn setup và debug trên iPhone vật lý.
Prerequisites
- Apple Developer account (free works, nhưng 7-day re-signing limit)
- Developer Mode trên iPhone: Settings > Privacy & Security > Developer Mode > ON (cần restart)
- Xcode signing: Mở project
src-tauri/gen/apple/app.xcodeproj→ chọn app_iOS target → Signing & Capabilities → Automatically manage signing → chọn Team - Trust profile (lần đầu): Trên iPhone: Settings > General > VPN & Device Management > Trust developer certificate
Network Setup
iPhone phải reach được Mac dev server (Vite).
Firewall
Mac firewall chặn incoming connections mặc định:
bash
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add $(which node)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp $(which node)Tailscale
Nếu dùng Tailscale VPN:
- Cả Mac và iPhone cần Tailscale
- Chọn Tailscale IP (
100.x.x.x) khi--force-ip-prompthỏi
Info.plist
File: src-tauri/gen/apple/app_iOS/Info.plist
| Key | Value | Lý do |
|---|---|---|
| NSAppTransportSecurity > NSAllowsArbitraryLoads | true | Cho phép HTTP dev server |
| NSLocalNetworkUsageDescription | String mô tả | Trigger Local Network permission |
| NSBonjourServices | _http._tcp | Discovery protocol |
Capabilities
File: src-tauri/capabilities/default.json
Quan trọng
Cần cả "windows": ["main"] VÀ "webviews": ["main"]. iOS dùng webviews, không phải windows.
Troubleshooting
| Vấn đề | Nguyên nhân | Fix |
|---|---|---|
| Màn hình đen, không lỗi | iPhone không reach Vite server | Kiểm tra network, firewall, --force-ip-prompt |
| "error sending request... local network" | iOS chặn Local Network | Thêm NSLocalNetworkUsageDescription, xóa app & cài lại |
| "Developer Mode disabled" | Chưa bật Developer Mode | Settings > Privacy & Security > Developer Mode > ON |
| Vite bind sai IP | TAURI_DEV_HOST bị override | Dùng --force-ip-prompt |
| "No code signing certificates" | Xcode chưa config signing | Mở .xcodeproj, set team |
Screenshot Debugging
Dùng pymobiledevice3 để chụp màn hình từ terminal:
bash
# Terminal 1: Start tunnel daemon (giữ chạy)
sudo python3 -m pymobiledevice3 remote tunneld -p tcp
# Terminal 2: Chụp screenshot
pymobiledevice3 developer dvt screenshot --tunnel DEVICE_UDID /tmp/screenshot.pngLấy UDID: xcrun devicectl list devices