Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.
🤖 Utilizando a WebView no Android Nativo
Este documento fornece um guia completo para implementar a WebView de biometria em aplicações Android nativas usando Kotlin e Jetpack Compose.
Configuração Inicial
Adicionando a Biblioteca AndroidX Webkit
Para utilizar os recursos do WebView mais recentes em compatibilidade com versões anteriores, adicione ao seu arquivo app/build.gradle a biblioteca AndroidX Webkit:
dependencies {
implementation("androidx.webkit:webkit:1.7.0")
}
Nota: Caso esteja utilizando uma versão do Kotlin igual ou superior a 1.8, utilize a versão 1.8.0 ou superior do Webkit.
Permissões no Manifesto
O app precisa ter acesso à Internet e à câmera. Adicione as seguintes permissões no seu arquivo de manifesto:
<manifest ... >
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA"/>
...
</manifest>
Implementação da WebView
Adicionando WebView com Jetpack Compose
O exemplo abaixo demonstra como adicionar uma WebView utilizando Jetpack Compose. Para exemplos de como utilizar XML ou direto na Activity, siga os passos da documentação oficial do Android.
AndroidView(factory = {
WebView(it).apply {
layoutParams = ViewGroup.LayoutParams(
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
clearCache(true)
settings.javaScriptEnabled = true
settings.mediaPlaybackRequiresUserGesture = false
settings.cacheMode = WebSettings.LOAD_NO_CACHE
isDebugInspectorInfoEnabled = BuildConfig.DEBUG
CookieManager.getInstance().setAcceptCookie(false)
CookieManager.getInstance().setAcceptThirdPartyCookies(this, false)
webViewClient = WebViewClient()
webChromeClient = WebChromeClient()
}
}, update = {
it.loadUrl("${URL}")
})
Explicação das Configurações
- AndroidView: Componente para incorporar a visualização do Android ao layout do Compose
- factory: Função que cria uma instância da visualização do Android
- update: Função para atualizar a visualização do Android
- clearCache(true): Garante que o cache de usos anteriores seja excluído em novas instâncias
- settings.javaScriptEnabled = true: Permite a execução de código JavaScript nas páginas web carregadas
- settings.mediaPlaybackRequiresUserGesture = false: Oculta os controles de reprodução de mídia
- settings.cacheMode = WebSettings.LOAD_NO_CACHE: Impede que o WebView mantenha cache do conteúdo carregado
- isDebugInspectorInfoEnabled = BuildConfig.DEBUG: Habilita o depurador da WebView em modo Debug
- CookieManager: Remove o uso de cookies na WebView
Vinculação do Código JavaScript ao Android
Criando a Classe BiometricsJS
Para vincular os eventos da página carregada no WebView ao aplicativo, utilizamos o método addJavascriptInterface(). Crie uma nova classe:
class BiometricsJS() {
@JavascriptInterface
fun postMessage(response: String) {
try {
Log.i("BiometricsJS", response)
val biometricsResp = Gson().fromJson(response, BiometricsWebViewRespModel::class.java)
when (biometricsResp.type) {
"OnFinished" -> {
when (biometricsResp.decision) {
"APPROVED", "DENIED" -> {
// O que deve ser feito quando receber o evento APPROVED ou DENIED
}
"CLOSE" -> {
// O que deve ser feito quando receber o evento CLOSE
}
}
}
"OnError" -> {
// O que deve ser feito quando receber o evento OnError
}
}
} catch (e: Exception) {
Log.e("BiometricsJS", e.message ?: "Error", e)
}
}
}
Adicionando a Interface JavaScript
No WebView, adicione o seguinte código:
...
WebView(it).apply {
...
addJavascriptInterface(
BiometricsJS(),
"BiometricsWebView"
)
...
}
...
Injetando Código JavaScript
Configurando a Inicialização
Para injetar o código JavaScript no WebView utilizamos o método evaluateJavascript. Neste exemplo, estamos injetando o JavaScript quando a página é carregada completamente:
...
WebView(it).apply {
...
webViewClient = object : WebViewClient() {
override fun onPageFinished(view: WebView, url: String?) {
// Qualquer outra ação que quiser adicionar
// ao finalizar o carregamento da página adicione aqui
view.evaluateJavascript(
"""(function(){
window.postMessage({
type: "OnInit",
detail: {
authorization: "${AUTHORIZATION}",
token: "${TOKEN}",
isOperador: ${IS_OPERATOR},
theme: {
primaryColor: "${PRIMARY_COLOR}",
buttonTextColor: "${BUTTON_TEXT_COLOR}"
}
}
});
window.addEventListener('message', (e) => {
if (e?.data?.type !== 'OnInit') {
window.BiometricsWebView.postMessage(JSON.stringify({ type: e?.data?.type, ...e?.data?.detail }));
}
});
})()""".trim(), null
)
}
}
...
}
...
Nota: O objeto
themeé opcional. Caso seja enviado, adicione as cores de acordo com o tema da sua aplicação.
Gerenciamento de Permissões
Solicitando Permissões de Recursos
Você deve solicitar as permissões de recursos necessárias antes de iniciar a WebView. Uma vez concedidas, sobrescreva o método onPermissionRequest do WebChromeClient:
...
WebView(it).apply {
...
webChromeClient = object : WebChromeClient() {
override fun onPermissionRequest(request: PermissionRequest?) {
request?.grant(request.resources)
}
}
...
}
...
Modelo de Dados
Certifique-se de criar o modelo BiometricsWebViewRespModel com os seguintes campos:
data class BiometricsWebViewRespModel(
val type: String,
val decision: String?,
val jwt: String?,
val base64: String?,
val code: Int?,
val message: String?
)
Pontos Importantes
- Sempre limpe o cache ao criar novas instâncias da WebView
- Solicite as permissões necessárias antes de inicializar a WebView
- O evento
OnInitdeve ser disparado após o carregamento completo da página - Utilize o modo Debug para facilitar o desenvolvimento e depuração
- Implemente tratamento de erros adequado na classe BiometricsJS