Permissões

O conteúdo da Web que chama navigator.mediaDevices.getUserMedia(), a API de geolocalização ou a API de notificações precisa que o aplicativo host conceda ou negue essas solicitações. O Wails disponibiliza um mapa multiplataforma Permissions em WebviewWindowOptions, permitindo controlar isso de forma declarativa, sem a necessidade de código específico para cada plataforma.

Início rápido

window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title: "My App",
    Permissions: map[application.PermissionType]application.Permission{
        application.PermissionMicrophone: application.PermissionAllow,
        application.PermissionCamera:     application.PermissionAllow,
    },
})

As solicitações de acesso à câmera e ao microfone feitas pelo conteúdo da Web dessa janela são concedidas sem que o navegador exiba uma solicitação de permissão.

Tipos de permissão

PermissionType (uint8) identifica um recurso que o conteúdo da Web pode solicitar.

Valores de permissão

Permission (uint8) é a política aplicada a um determinado tipo.

PermissionDefault é o valor zero; portanto, as entradas não definidas no mapa usam o comportamento padrão.

Comportamento nas plataformas

Cada plataforma trata PermissionDefault de maneira diferente porque suas webviews subjacentes têm comportamentos nativos distintos.

Linux (WebKitGTK)

O WebKitGTK não tem uma solicitação de permissão nativa. Sem um manipulador associado, ele nega silenciosamente todas as solicitações — por isso, getUserMedia sempre retornava NotAllowedError antes da adição desse recurso.

Atualmente, no Linux, o Wails trata solicitações de acesso à câmera e ao microfone. A geolocalização, as notificações e a leitura da área de transferência ainda não estão integradas e continuam sendo negadas, independentemente da política definida.

Windows (WebView2)

O WebView2 tem uma solicitação de permissão nativa e uma API de permissões por tipo. Os cinco tipos de recurso são totalmente compatíveis.

Importante: antes da existência desse recurso, o Wails chamava SetGlobalPermission(Allow) incondicionalmente, concedendo silenciosamente todos os recursos. Agora, quando há qualquer entrada em Permissions, essa concessão geral não é definida. Os recursos não definidos passam a exibir a solicitação nativa do WebView2, em vez de serem concedidos automaticamente.

Isso significa que, se você configurar Permissions de qualquer forma no Windows, todo recurso que não estiver listado explicitamente exibirá uma solicitação de permissão, em vez de ser permitido silenciosamente. Defina explicitamente os recursos necessários.

macOS (WKWebView + TCC)

No macOS, duas camadas precisam concordar. O WKWebView consulta o aplicativo antes de iniciar a captura, e o mapa Permissions responde a essa solicitação. Abaixo dele, a estrutura de privacidade TCC controla o próprio dispositivo: a solicitação do sistema aparece no primeiro acesso real à câmera ou ao microfone, e a escolha fica registrada por aplicativo em Ajustes do Sistema → Privacidade e Segurança.

O Wails trata solicitações de câmera e microfone no macOS 12 ou posterior. Geolocalização, notificações e leitura da área de transferência não têm equivalente em WKUIDelegate, portanto não estão conectadas e ficam a cargo do TCC. Como no Linux, a política definida para elas não tem efeito.

PermissionAllow permite a solicitação da webview, não o acesso ao dispositivo. A autorização do sistema continua independente, e um aplicativo negado nos Ajustes do Sistema continua negado. Apenas a solicitação do próprio WebKit é omitida.

Antes do macOS 12, esse método de delegate não existe, então o mapa é ignorado e todas as solicitações retornam à confirmação do WebKit.

Verifique se Info.plist inclui as chaves de descrição de uso apropriadas:

<key>NSMicrophoneUsageDescription</key>
<string>Used for voice input</string>
<key>NSCameraUsageDescription</key>
<string>Used for video calls</string>

Padrões comuns

Aplicativo de captura de mídia

Conceda acesso à câmera e ao microfone em todas as plataformas:

Permissions: map[application.PermissionType]application.Permission{
    application.PermissionMicrophone: application.PermissionAllow,
    application.PermissionCamera:     application.PermissionAllow,
},

No Linux, isso permite explicitamente ambos os dispositivos; os demais recursos continuam bloqueados. No Windows, isso permite ambos; qualquer outro recurso que você não listar exibirá uma solicitação nativa. No macOS, isso permite ambos na camada WebKit, sem solicitação do navegador. O TCC ainda solicita acesso aos próprios dispositivos no primeiro uso, e ambas as chaves de descrição de uso devem estar em Info.plist.

Bloquear a captura de mídia no Linux

Por padrão, o Linux permite o acesso à câmera e ao microfone. Para desativá-lo:

Permissions: map[application.PermissionType]application.Permission{
    application.PermissionMicrophone: application.PermissionDeny,
    application.PermissionCamera:     application.PermissionDeny,
},

Permitir todos os recursos no Windows

Para permitir todos os recursos sem exibir solicitações:

Permissions: map[application.PermissionType]application.Permission{
    application.PermissionMicrophone:    application.PermissionAllow,
    application.PermissionCamera:        application.PermissionAllow,
    application.PermissionGeolocation:   application.PermissionAllow,
    application.PermissionNotifications: application.PermissionAllow,
    application.PermissionClipboardRead: application.PermissionAllow,
},

Políticas por janela

Janelas diferentes podem ter políticas diferentes:

// Main app window — full media access
mainWindow := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title: "App",
    Permissions: map[application.PermissionType]application.Permission{
        application.PermissionMicrophone: application.PermissionAllow,
        application.PermissionCamera:     application.PermissionAllow,
    },
})

// Settings window — no special capabilities
settingsWindow := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title: "Settings",
    // No Permissions entry — uses platform defaults
})

// Embedded content window — deny media capture
embeddedWindow := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title: "Embedded",
    Permissions: map[application.PermissionType]application.Permission{
        application.PermissionMicrophone: application.PermissionDeny,
        application.PermissionCamera:     application.PermissionDeny,
    },
})

Substituição específica do Windows

O campo Windows.Permissions por janela (map[CoreWebView2PermissionKind]CoreWebView2PermissionState) continua funcionando e pode substituir as configurações de recursos individuais depois que o mapa multiplataforma é aplicado. Use-o quando precisar acessar tipos de permissão do WebView2 que não tenham um equivalente multiplataforma (por exemplo, CoreWebView2PermissionKindOtherSensors).

Windows: application.WindowsWindow{
    Permissions: map[application.CoreWebView2PermissionKind]application.CoreWebView2PermissionState{
        application.CoreWebView2PermissionKindOtherSensors: application.CoreWebView2PermissionStateAllow,
    },
},

A ordem de avaliação no Windows é:

1. Mapa multiplataforma Permissions (define o estado de cada tipo por meio de SetPermission)
2. Mapa Windows.Permissions (substitui tipos individuais)
3. Para qualquer tipo não abrangido por nenhum dos mapas: solicitação nativa do WebView2 (quando uma política está configurada) ou permissão automática (quando nenhuma política está configurada — o comportamento legado)

Matriz de compatibilidade entre plataformas

Quando o macOS indica ✅, a política responde ao WebKit; o TCC também controla o dispositivo. Quando indica ❌, o recurso fica a cargo somente do TCC.

Solução de problemas

getUserMedia continua falhando no Linux após a atualização

Verifique se você não definiu explicitamente PermissionMicrophone: PermissionDeny nem PermissionCamera: PermissionDeny. O padrão (não definido) permite a captura de mídia no Linux.

O Windows está solicitando permissões que eu não configurei

Quando há alguma entrada em Permissions, o Wails deixa de definir a permissão geral Allow. Os recursos que você não listar exibirão a solicitação nativa do WebView2. Adicione entradas PermissionAllow explícitas para todos os recursos usados pelo seu aplicativo.

As permissões do macOS não estão funcionando

Permissions cobre câmera e microfone no macOS 12 ou posterior; geolocalização, notificações e leitura da área de transferência ainda não estão conectadas e ignoram a política. O TCC continua controlando o dispositivo: PermissionAllow remove a solicitação do WebKit, mas não a do sistema. Verifique as chaves NSMicrophoneUsageDescription e NSCameraUsageDescription em Info.plist e a autorização em Ajustes do Sistema → Privacidade e Segurança.

Meu aplicativo macOS encerra quando o conteúdo web solicita a câmera ou o microfone

Verifique se Info.plist contém NSCameraUsageDescription ou NSMicrophoneUsageDescription para cada dispositivo solicitado. A ausência de descrições pode causar a rejeição da solicitação; acessar o AVFoundation sem uma descrição obrigatória pode encerrar o aplicativo. PermissionDeny controla a decisão do WebKit e não substitui essas chaves.

Geolocalização, notificações e área de transferência não têm efeito no Linux

Atualmente, somente a câmera e o microfone são tratados no Linux. A compatibilidade com outros tipos de recurso ainda não foi implementada — eles permanecem bloqueados independentemente da política definida.