Get started
Introduction
Installation
Your first app
Tutorials
Fission tutorials
Handle unsupported iOS Wi-Fi operations with Fission
Core concepts
Components
State and effects
Protected routes
Server-side rendering
Styling
Testing
Deployment
Reference
API reference
Cookbook
Fission 0.16.0
Documentation version
Read the changelog →

Handle unsupported iOS Wi-Fi operations with Fission

Report an unsupported Wi-Fi request and keep the user's working note available whilst they configure the network manually.
iOS

What you will build

Handle the current iOS Wi-Fi boundary without claiming that opening Settings establishes connectivity.
Request the actual scan and decode its unsupported result
Keep the note and a manual Settings path available
Distinguish network configuration from a confirmed connection or successful upload
An unsupported scan and an empty scan are not the same result. An empty result means a host performed the operation and returned no matching networks. Unsupported means it cannot perform that operation at all. Calling either one "no Wi-Fi" would send the user towards the wrong recovery step.
Fission's default iOS host does not implement Wi-Fi scanning or connection. This tutorial is deliberately about handling that boundary, as its goal states, not adding native Wi-Fi support. We will issue the real capability request, show its typed result and leave a working note intact whilst the user configures a network manually.

Create the app

Complete iOS setup if needed.
cargo install cargo-fission
fission init ios-use-fissions-constrained-ios-wi-fi-capability
cd ios-use-fissions-constrained-ios-wi-fi-capability
fission add-target ios --project-dir .
fission add-capability wifi --project-dir .
cargo add serde_yaml
The capability command records the feature and synchronizes its platform metadata. It does not install a native Wi-Fi implementation. Keep the generated src/main.rs; the shared library below runs the same error-handling screen on native and Web targets without a memory provider.

Run the finished example

fission run --target ios --project-dir .

1. Decode the host's result rather than creating one

The scan reducer binds unit completion actions, requests the typed operation and returns immediately. Its completion reads cx.input. A real unsupported error receives its own status instead of being disguised as denial, a successful empty list or a prepared upload.
Only one scan is admitted at a time. The working note remains editable and is not replaced by either completion path. The last successful scan, if a different host supplies one, is labelled as historical rather than displayed as proof of the current network.
{"id":"fission-tabs-1","tabs":[{"index":0,"label":"src/app.rs","value":"src-app-rs"},{"index":1,"label":"src/app/state.rs","value":"src-app-state-rs"},{"index":2,"label":"src/app/screen.rs","value":"src-app-screen-rs"},{"index":3,"label":"src/i18n.rs","value":"src-i18n-rs"},{"index":4,"label":"src/lib.rs","value":"src-lib-rs"},{"index":5,"label":"preview/lib.rs","value":"preview-lib-rs"},{"index":6,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"},{"index":7,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}]}
{"id":"fission-tabs-1","index":0,"label":"src/app.rs","value":"src-app-rs"}
mod screen;
pub mod state;
pub use screen::NetworkNoteScreen;
pub use state::NetworkNoteState;
{"id":"fission-tabs-1","index":1,"label":"src/app/state.rs","value":"src-app-state-rs"}
use fission::prelude::*;

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct NetworkNoteState {
    pub locale: Locale,
    pub note: String,
    pub pending: bool,
    pub status_key: String,
    pub result: Option<WifiScanResult>,
    pub error: Option<String>,
}

impl Default for NetworkNoteState {
    fn default() -> Self {
        Self {
            locale: Locale::from("en-US"),
            note: String::new(),
            pending: false,
            status_key: "network.ready".into(),
            result: None,
            error: None,
        }
    }
}
impl GlobalState for NetworkNoteState {}

pub fn try_scan(state: &mut NetworkNoteState, cx: &mut ReducerContext<NetworkNoteState>) {
    if state.pending {
        return;
    }
    state.pending = true;
    state.status_key = "network.pending".into();
    state.error = None;
    let ok = cx.effects.bind(ScanReturned, reduce_with!(scan_returned));
    let err = cx.effects.bind(ScanFailed, reduce_with!(scan_failed));
    cx.effects
        .wifi()
        .scan_networks(WifiScanRequest {
            ssid_prefix: None,
            include_hidden: false,
            timeout_ms: Some(5_000),
        })
        .on_ok(ok)
        .on_err(err);
}

#[fission_reducer(ScanReturned)]
fn scan_returned(state: &mut NetworkNoteState, cx: &mut ReducerContext<NetworkNoteState>) {
    state.pending = false;
    match cx.input.capability_ok(SCAN_WIFI_NETWORKS) {
        Some(result) => {
            state.result = Some(result);
            state.status_key = "network.returned".into();
        }
        None => state.status_key = "network.unexpected".into(),
    }
}

#[fission_reducer(ScanFailed)]
fn scan_failed(state: &mut NetworkNoteState, cx: &mut ReducerContext<NetworkNoteState>) {
    state.pending = false;
    let error = cx.input.capability_error(SCAN_WIFI_NETWORKS);
    state.status_key = if error
        .as_ref()
        .is_some_and(|error| error.code == "unsupported")
    {
        "network.unsupported"
    } else {
        "network.failed"
    }
    .into();
    state.error = error
        .map(|error| format!("{}: {}", error.code, error.message))
        .or_else(|| {
            cx.input
                .capability_error_message(SCAN_WIFI_NETWORKS)
                .map(str::to_owned)
        });
}
{"id":"fission-tabs-1","index":2,"label":"src/app/screen.rs","value":"src-app-screen-rs"}
use super::state::{try_scan, NetworkNoteState};
use fission::prelude::*;

fission_component! {
    pub NetworkNoteScreen<NetworkNoteState> {}
    view(_screen, state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } => SafeArea(
        child: Scroll(
            child: Container(Column(gap: tokens.spacing.m, children: [
                Text(cx.tr("network.heading")).size(tokens.typography.heading2_size),
                Text(cx.tr("network.explanation")),
                Row(gap: tokens.spacing.s, children: [
                    Button(
                        child: Text(cx.tr("language.english")), key: "english",
                        on_press: reduce { state.locale = Locale::from("en-US"); },
                    ),
                    Button(
                        child: Text(cx.tr("language.spanish")), key: "spanish",
                        on_press: reduce { state.locale = Locale::from("es-ES"); },
                    ),
                ]),
                TextInput(
                    value: state.note.clone(), bind(on_input): to(state.note),
                    label: Some(TextContent::Key("network.note".into())),
                    multiline: true, keyboard_type: TextInputType::Multiline,
                ),
                Button(
                    child: Text(cx.tr("network.try")), key: "try-wifi-scan",
                    disabled: state.pending,
                    on_press: reduce { try_scan(state, cx); },
                ),
                if state.pending {
                    Spinner(motion: Some(SpinnerMotion::Default), label: Some(cx.tr("network.pending")))
                },
                Text(cx.tr(&state.status_key)),
                if let Some(error) = &state.error { Code(text: error.clone()) },
                if let Some(result) = &state.result {
                    Text(cx.tr("network.last_count").replace("{count}", &result.networks.len().to_string()))
                },
                Text(cx.tr("network.manual")).weight(tokens.typography.font_weight_semibold),
                Text(cx.tr("network.manual_steps")),
                Text(cx.tr("network.not_connected")).color(tokens.colors.text_secondary),
                Text(cx.tr("network.session")).color(tokens.colors.text_secondary),
            ]))
            .padding_all(tokens.spacing.l),
        ),
    )
}
{"id":"fission-tabs-1","index":3,"label":"src/i18n.rs","value":"src-i18n-rs"}
use fission::i18n::{Locale, TranslationBundle};
use fission::prelude::*;
use std::collections::HashMap;

pub fn create_env() -> Env {
    let mut env = Env::default();
    env.locale = Locale::from("en-US");
    for (locale, source) in [
        ("en-US", include_str!("../i18n/en-US.yaml")),
        ("es-ES", include_str!("../i18n/es-ES.yaml")),
    ] {
        let messages: HashMap<String, String> =
            serde_yaml::from_str(source).expect("valid network note translations");
        env.i18n.add_bundle(TranslationBundle {
            locale: Locale::from(locale),
            messages,
        });
    }
    env
}

pub fn sync_env(state: &crate::app::NetworkNoteState, env: &mut Env) {
    env.locale = state.locale.clone();
}
{"id":"fission-tabs-1","index":4,"label":"src/lib.rs","value":"src-lib-rs"}
pub mod app;
mod i18n;

use app::{NetworkNoteScreen, NetworkNoteState};
use fission::prelude::*;

#[cfg(not(any(target_arch = "wasm32", target_os = "android", target_os = "ios")))]
pub fn run_desktop() -> anyhow::Result<()> {
    DesktopApp::<NetworkNoteState, _>::new(NetworkNoteScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
}

#[cfg(any(target_os = "android", target_os = "ios"))]
pub fn run_mobile() -> anyhow::Result<()> {
    MobileApp::<NetworkNoteState, _>::new(NetworkNoteScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
}

#[cfg(target_os = "android")]
#[no_mangle]
fn android_main(app_handle: AndroidApp) {
    let _ = MobileApp::<NetworkNoteState, _>::new(NetworkNoteScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run_with_android_app(app_handle);
}

#[cfg(target_arch = "wasm32")]
#[wasm_bindgen::prelude::wasm_bindgen(start)]
pub fn run_web() -> Result<(), wasm_bindgen::JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<NetworkNoteState, _>::new(NetworkNoteScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .run()
        .map_err(|error| wasm_bindgen::JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":5,"label":"preview/lib.rs","value":"preview-lib-rs"}
mod app;
mod i18n;

use fission::prelude::*;
use wasm_bindgen::prelude::*;

#[wasm_bindgen(start)]
pub fn run() -> Result<(), JsValue> {
    console_error_panic_hook::set_once();
    WebApp::<app::NetworkNoteState, _>::new(app::NetworkNoteScreen)
        .with_env(i18n::create_env())
        .with_sync_env(i18n::sync_env)
        .mount("#fission-web-mount")
        .run()
        .map_err(|error| JsValue::from_str(&error.to_string()))
}
{"id":"fission-tabs-1","index":6,"label":"i18n/en-US.yaml","value":"i18n-en-us-yaml"}
network.heading: "Keep working when Wi-Fi scanning is unavailable"
network.explanation: "Fission's current iOS host does not scan or join Wi-Fi networks. This screen handles that actual capability result without losing your note."
network.note: "Your working note"
network.try: "Try the host's Wi-Fi scan"
network.ready: "No scan has been requested."
network.pending: "Waiting for the host's scan result…"
network.returned: "The host returned a scan result. This does not establish internet access."
network.unsupported: "This host does not support Wi-Fi scanning. Configure the network manually and return to your note."
network.failed: "The scan failed. Review the details or use the manual setup path."
network.unexpected: "The host returned no usable scan result."
network.last_count: "Last successful scan: {count} network records"
network.manual: "Connect manually"
network.manual_steps: "Open iOS Settings, choose Wi-Fi, select your intended network and complete its connection steps. Return to this app afterwards."
network.not_connected: "Returning to this screen does not prove a connection or upload anything. Verify the operation your app actually needs."
network.session: "Your note remains in this running app, but it is not saved to disk. Closing or reloading the app clears it."
language.english: "English"
language.spanish: "Español"
{"id":"fission-tabs-1","index":7,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}
network.heading: "Seguir trabajando sin búsqueda de Wi-Fi"
network.explanation: "El host actual de Fission para iOS no busca redes ni se conecta a Wi-Fi. Esta pantalla trata el resultado real sin perder tu nota."
network.note: "Tu nota de trabajo"
network.try: "Probar la búsqueda de Wi-Fi del host"
network.ready: "No se ha solicitado ninguna búsqueda."
network.pending: "Esperando el resultado de la búsqueda…"
network.returned: "El host devolvió un resultado. Esto no demuestra acceso a internet."
network.unsupported: "Este host no admite la búsqueda de Wi-Fi. Configura la red manualmente y vuelve a tu nota."
network.failed: "La búsqueda ha fallado. Revisa los detalles o configura la red manualmente."
network.unexpected: "El host no devolvió un resultado utilizable."
network.last_count: "Última búsqueda correcta: {count} registros de red"
network.manual: "Conectar manualmente"
network.manual_steps: "Abre Ajustes de iOS, elige Wi-Fi, selecciona la red que necesitas y completa la conexión. Después vuelve a esta aplicación."
network.not_connected: "Volver aquí no demuestra una conexión ni sube ningún archivo. Comprueba la operación que tu aplicación necesita."
network.session: "Tu nota permanece en la aplicación abierta, pero no se guarda en disco. Cerrar o recargar la aplicación la borra."
language.english: "Inglés"
language.spanish: "Español"
{"id":"fission-tabs-1"}
Write a note, then try the scan. On the default iOS and Web hosts, expect an unsupported result rather than sample networks. Check that the pending indicator stops and your note remains unchanged. Retry once to verify the screen is not stuck.
Show the app preview
Hide the app preview

2. Provide a manual path without inventing connection success

The screen explains how to use iOS Settings. It does not use an undocumented URL to jump directly into the Wi-Fi pane, and it does not ask the user for a network password that this app cannot use.
Returning from Settings leaves the running app's note available. It does not prove a connection succeeded, that a captive portal has been completed or that your server is reachable. In a real upload workflow, the upload's actual response would establish that operation's success; a Wi-Fi scan is not its authority.
The default unsupported provider's availability object reports disabled/denied/no network. Do not interpret that placeholder as an observed iPhone radio state. The typed unsupported scan error is the relevant capability boundary here.
Leave the running app for Settings and return. Verify the note if the process remains alive, but do not claim process-restart persistence. No button should mark a report uploaded merely because you returned.
Show the app preview
Hide the app preview

3. Check the native fallback and the capability contract separately

fission doctor ios --project-dir .
fission devices --project-dir .
fission run --target ios --project-dir .
fission test --target ios --project-dir .
Select a simulator with the simulator guide, then repeat on an iPhone using the installation guide. Listen to the unsupported message with VoiceOver and check both languages at narrow widths.
A test provider belongs in test infrastructure when checking success, timeout or malformed completion handling. It must not silently replace the normal provider in the published preview or native launcher. A test with invented networks proves result handling, not iOS scanning.
Adding a native Wi-Fi provider would be a separate upstream implementation, with its own OS restrictions, permissions and qualification. This page does not claim that work is complete.