Get started
Introduction
Installation
Your first app
Tutorials
Fission tutorials
Configure iOS permissions and privacy descriptions for Fission capabilities
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 →

Configure iOS permissions and privacy descriptions for Fission capabilities

Request real camera permission for a caption draft and connect each capability's native metadata to its actual provider support.
iOS

What you will build

Keep native purpose text, runtime permission and a completed operation distinct when configuring iOS capabilities.
Replace generic camera purpose text with the app's actual reason
Request permission only after an explicit user action
Preserve the caption through denied, restricted, unknown and unsupported responses
A capability declaration, permission grant and completed operation are three different facts. A camera usage description lets iOS explain a request; it does not grant access, take a photograph or prove the app has a working provider.
We will implement a real camera-permission request beside an editable photo-caption draft. The draft remains useful when access is denied or restricted. No status will say a photo was attached merely because the operating system allowed the next step.

Configure only the capability this app requests

Complete iOS setup first if needed.
cargo install cargo-fission
fission init ios-configure-ios-permissions-and-privacy-descriptions-for-fission-capabilities
cd ios-configure-ios-permissions-and-privacy-descriptions-for-fission-capabilities
fission add-target ios --project-dir .
fission add-capability camera --project-dir .
cargo add serde_yaml
Inspect platforms/ios/Info.plist and its NSCameraUsageDescription. The current CLI inserts a generic purpose string when the key is absent and preserves an existing key during capability synchronization. Replace that string with an accurate explanation for this app, keep the intended platform input under version control and inspect regeneration diffs. Do not invent a fission.toml privacy-description field which the current configuration does not expose.
For example, this permission-readiness screen can explain: "Camera access is requested when you choose to prepare a photo attachment." A production capture screen should describe the actual photograph's use, not imply every feature needs unrestricted access.

Run the finished example

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

1. Request access from the user's action

Keep the generated src/main.rs and add the shared files below. Both normal native and Web launchers use the real provider available to that target. The view never requests permission during conversion or automatically retries after denial.
A granted response is labelled as the last permission response, not a permanent promise about device state. Requesting again after a Settings change asks the host for its current result; it does not reuse an invented grant from app state.
{"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::PhotoAccessScreen;
pub use state::PhotoAccessState;
{"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 PhotoAccessState {
    pub locale: Locale,
    pub pending: bool,
    pub permission: Option<CameraPermission>,
    pub status_key: String,
    pub error: Option<String>,
}

impl Default for PhotoAccessState {
    fn default() -> Self {
        Self {
            locale: Locale::from("en-US"),
            pending: false,
            permission: None,
            status_key: "photo.ready".into(),
            error: None,
        }
    }
}
impl GlobalState for PhotoAccessState {}

pub fn request_access(state: &mut PhotoAccessState, cx: &mut ReducerContext<PhotoAccessState>) {
    if state.pending {
        return;
    }
    state.pending = true;
    state.error = None;
    state.status_key = "photo.pending".into();
    let ok = cx
        .effects
        .bind(PermissionReturned, reduce_with!(permission_returned));
    let err = cx
        .effects
        .bind(PermissionFailed, reduce_with!(permission_failed));
    cx.effects
        .camera()
        .request_permission(CameraPermissionRequest { reason: None })
        .on_ok(ok)
        .on_err(err);
}

#[fission_reducer(PermissionReturned)]
fn permission_returned(state: &mut PhotoAccessState, cx: &mut ReducerContext<PhotoAccessState>) {
    state.pending = false;
    state.permission = cx.input.capability_ok(REQUEST_CAMERA_PERMISSION);
    state.status_key = match state.permission {
        Some(CameraPermission::Granted) => "photo.granted",
        Some(CameraPermission::Denied) => "photo.denied",
        Some(CameraPermission::Restricted) => "photo.restricted",
        Some(CameraPermission::Unknown) => "photo.unknown",
        None => "photo.unexpected",
    }
    .into();
}

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

fission_component! {
    pub PhotoAccessScreen<PhotoAccessState> {
        state { caption: String = String::new() }
    }
    view(form, state, cx) {
        let tokens = &cx.view.env().theme.tokens;
    } => SafeArea(
        child: Scroll(
            child: Container(Column(gap: tokens.spacing.m, children: [
                Text(cx.tr("photo.heading")).size(tokens.typography.heading2_size),
                Text(cx.tr("photo.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: form.caption.clone(), bind(on_input): to(form.caption),
                    label: Some(TextContent::Key("photo.caption".into())),
                    helper_text: Some(TextContent::Key("photo.caption_help".into())),
                    multiline: true, keyboard_type: TextInputType::Multiline,
                ),
                Button(
                    child: Text(cx.tr("photo.request")), key: "request-camera-access",
                    disabled: state.pending,
                    on_press: reduce { request_access(state, cx); },
                ),
                if state.pending {
                    Spinner(motion: Some(SpinnerMotion::Default), label: Some(cx.tr("photo.pending")))
                },
                Text(cx.tr("photo.last_response")).weight(tokens.typography.font_weight_semibold),
                Text(cx.tr(&state.status_key)),
                if let Some(error) = &state.error { Code(text: error.clone()) },
                Text(cx.tr("photo.scope")).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 photo access translations");
        env.i18n.add_bundle(TranslationBundle {
            locale: Locale::from(locale),
            messages,
        });
    }
    env
}

pub fn sync_env(state: &crate::app::PhotoAccessState, 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::{PhotoAccessScreen, PhotoAccessState};
use fission::prelude::*;

#[cfg(not(any(target_arch = "wasm32", target_os = "android", target_os = "ios")))]
pub fn run_desktop() -> anyhow::Result<()> {
    DesktopApp::<PhotoAccessState, _>::new(PhotoAccessScreen)
        .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::<PhotoAccessState, _>::new(PhotoAccessScreen)
        .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::<PhotoAccessState, _>::new(PhotoAccessScreen)
        .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::<PhotoAccessState, _>::new(PhotoAccessScreen)
        .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::PhotoAccessState, _>::new(app::PhotoAccessScreen)
        .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"}
photo.heading: "Prepare a photo attachment"
photo.explanation: "A photo can add context to your note. Request camera access when you choose that feature; you can keep writing without it."
photo.caption: "What would the photo show?"
photo.caption_help: "This draft remains editable if camera access is unavailable."
photo.request: "Request camera access"
photo.last_response: "Last camera permission response"
photo.ready: "Camera access has not been requested."
photo.pending: "Waiting for the camera permission response…"
photo.granted: "The host reported camera access granted. No photograph has been taken."
photo.denied: "Access was denied. You can review this app's camera permission in iOS Settings or continue writing."
photo.restricted: "Access is restricted. It may require a device-management or parental-control change; you can continue writing."
photo.unknown: "The permission state remains unknown. No photograph has been taken."
photo.unexpected: "The host returned no usable permission result."
photo.unsupported: "This host does not support the camera permission operation."
photo.failed: "The permission operation failed. Your draft is unchanged."
photo.scope: "This example checks permission only. It does not capture, attach, upload or save a photo or note."
language.english: "English"
language.spanish: "Español"
{"id":"fission-tabs-1","index":7,"label":"i18n/es-ES.yaml","value":"i18n-es-es-yaml"}
photo.heading: "Preparar una foto adjunta"
photo.explanation: "Una foto puede dar contexto a tu nota. Solicita acceso a la cámara al elegir esa función; puedes seguir escribiendo sin ella."
photo.caption: "¿Qué mostraría la foto?"
photo.caption_help: "Este borrador sigue siendo editable si la cámara no está disponible."
photo.request: "Solicitar acceso a la cámara"
photo.last_response: "Última respuesta de permiso de cámara"
photo.ready: "No se ha solicitado acceso a la cámara."
photo.pending: "Esperando la respuesta de permiso de cámara…"
photo.granted: "El host indicó que se concedió acceso. No se ha tomado ninguna foto."
photo.denied: "Se denegó el acceso. Puedes revisar el permiso de cámara de esta app en Ajustes o seguir escribiendo."
photo.restricted: "El acceso está restringido. Puede requerir un cambio de gestión del dispositivo o control parental; puedes seguir escribiendo."
photo.unknown: "El permiso sigue siendo desconocido. No se ha tomado ninguna foto."
photo.unexpected: "El host no devolvió un resultado de permiso utilizable."
photo.unsupported: "Este host no admite la operación de permiso de cámara."
photo.failed: "La operación de permiso falló. Tu borrador no ha cambiado."
photo.scope: "Este ejemplo solo comprueba el permiso. No captura, adjunta, sube ni guarda fotos o notas."
language.english: "Inglés"
language.spanish: "Español"
{"id":"fission-tabs-1"}
Write a caption, request access and inspect the actual result. Refuse permission in a fresh permission context and confirm that the draft remains editable and the pending indicator stops. A granted result must not claim a photo has been taken.
Show the app preview
Hide the app preview

2. Map platform metadata without confusing it with provider support

The current generator uses these native inputs for declared capabilities. Add only those the application needs, not the whole list as a precaution.
Declared capability
Generated iOS metadata or additional requirement
Camera or barcode scanner
NSCameraUsageDescription
Geolocation
NSLocationWhenInUseUsageDescription
Microphone
NSMicrophoneUsageDescription
Biometric
NSFaceIDUsageDescription; a description does not supply the currently missing native provider
Bluetooth
NSBluetoothAlwaysUsageDescription; a real iOS Bluetooth provider is separate
NFC
NFCReaderUsageDescription and NDEF reader entitlement; a real Core NFC provider is separate
Wi-Fi
Location purpose text and Wi-Fi-related entitlements; default iOS Wi-Fi operations remain unsupported
Passkeys
Product-specific Associated Domains/webcredentials configuration is separate; the capability command does not implement AuthenticationServices
Local notifications
No Info.plist usage-description key from this scaffold; notification authorization is a runtime request
Haptics or volume control
No iOS usage-description key from this scaffold; that does not imply every volume operation is implemented
The Rust translation bundles localize this screen. They do not automatically localize iOS privacy-purpose strings or package InfoPlist.strings resources. Treat native prompt localization as a separate resource and packaging check rather than assuming the Spanish screen changes the operating system's purpose text.
Permission denial and restriction also have different recovery paths. An ordinary denial may be changed in Settings; a restriction may come from management or parental policy which the user cannot change in the app. Neither result should produce repeated automatic prompts or erase their work.
Inspect the actual packaged app's metadata as well as the platform input file. A source key is not proof that the final signed artifact contains the intended purpose text and entitlements.
Show the app preview
Hide the app preview

3. Verify the prompt and the recovery path on iOS

fission doctor ios --project-dir .
fission devices --project-dir .
fission run --target ios --project-dir .
fission test --target ios --project-dir .
Use the simulator guide for selection and the iPhone guide for signed-device qualification. Test a first request, denial, a later Settings change and an unavailable or restricted context where you can reproduce it. Do not record an untested restriction as a pass just because the enum has that variant.
The browser exercises its own permission policy, not iOS's Info.plist or entitlement enforcement. A launch smoke test does not interact with the prompt or listen to VoiceOver. Check both languages, the actual native prompt and whether the user can continue writing when access is unavailable.
For the next operation after permission, use camera capture. Keeping this step about permission makes its result precise; capturing, consuming and exporting image bytes is a separate task.