Idle Detection API no JavaScript: Detectar Inatividade do Usuário

Aprenda a usar a Idle Detection API no JavaScript para detectar inatividade no navegador e criar funções inteligentes em sites e apps web modernos.

Em resumo: a Idle Detection API é uma interface do navegador que permite detectar quando o usuário está inativo — sem interação com teclado e mouse ou com a tela bloqueada. Com ela, aplicações web podem reagir à inatividade: pausar notificações, salvar o trabalho automaticamente, deslogar por segurança ou atualizar o status de presença em apps de chat.

Introdução – Idle Detection API

A Idle Detection API no JavaScript chegou trazendo uma possibilidade poderosa para você que quer desenvolver aplicações web modernas: detectar quando o usuário está inativo no navegador.

Na prática, isso significa que você pode criar experiências mais inteligentes, seguras e dinâmicas — como deslogar automaticamente depois de um tempo parado, pausar um vídeo, mostrar uma mensagem de alerta ou até acionar automações no seu sistema.

E o melhor: tudo isso de forma nativa, sem plugins externos.

Se você já pensou em como grandes plataformas conseguem saber quando você “sumiu da tela”, esse é exatamente o tipo de solução que elas usam. E agora você vai entender como aplicar isso no seu próprio projeto.

Aqui, eu vou te mostrar o passo a passo de como usar a Idle Detection API no JavaScript, começando pelo básico, entendendo como ela funciona e chegando ao código real para detectar inatividade do usuário no navegador.

No final desse conteúdo, você vai ser capaz de implementar essa funcionalidade do zero e já vai ter ideias de como usar essa API no seu site, app ou dashboard web. Bora aprender juntos e deixar seu front-end muito mais inteligente?

Para fazer o download do(s) arquivo(s) utilizados na aula, preencha com o seu e-mail:

Não vamos te encaminhar nenhum tipo de SPAM! A Hashtag Treinamentos é uma empresa preocupada com a proteção de seus dados e realiza o tratamento de acordo com a Lei Geral de Proteção de Dados (Lei n. 13.709/18). Qualquer dúvida, nos contate.

O que é a Idle Detection API

A Idle Detection API é um recurso moderno do navegador que permite ao seu site identificar quando o usuário está ativo ou inativo, e também se a tela está bloqueada ou desbloqueada.

Em outras palavras: ela dá ao JavaScript a capacidade de entender o comportamento do usuário e agir de forma inteligente sempre que houver um período de inatividade.

Essa API surgiu para resolver uma necessidade real do front-end moderno: garantir segurança, experiência do usuário e automações baseadas em presença.

Em sistemas bancários, plataformas de streaming, ferramentas corporativas e apps web, detectar a inatividade virou padrão. Agora, você pode implementar isso sem gambiarras, timers gigantes ou plugins externos.

Resumo - ela monitora duas coisas:

• userState: active ou idle
• screenState: locked ou unlocked

Para que serve

A Idle Detection API serve para criar experiências mais inteligentes e seguras. Ela permite que o navegador “avise” seu JavaScript quando o usuário estiver sem interação por um período (ex.: 60 segundos), e você decide o que fazer com essa informação.

Por exemplo:

• Segurança: bloquear conta após inatividade
• UX: mostrar lembrete após X segundos sem movimento
• Apps corporativos: detectar sessões ociosas
• Produtividade: pausar tarefas ou timers quando o usuário sai

Com isso, você substitui soluções caseiras como setTimeout() e entra no mundo de controle baseado em eventos reais do sistema. Mais precisão, menos código.

Exemplo de lógica:

Se userState = "idle" E tempo >= 60 segundos
→ mostrar alerta / encerrar sessão / pausar conteúdo

Tempo mínimo recomendado pela API: 60 segundos

Exemplos de uso prático (bancos, vídeos, segurança)

Essa API já é usada em vários cenários comuns, mesmo quando você nem percebe:

Exemplo real no navegador: O usuário fica 1 minuto sem mexer → status muda para idle → função dispara.

Isso dá pra combinar com timers, pop-ups e até animações. Seu site reage ao usuário em tempo real.

Como funciona a Idle Detection API no JavaScript

A Idle Detection API funciona como um “sensor” dentro do navegador. Ela observa o uso do mouse, teclado e até o bloqueio da tela do sistema operacional.

Quando um desses estados muda, o usuário inativa, volta a interagir ou bloqueia a tela, o JavaScript recebe esse aviso e você pode reagir imediatamente com código.

A ideia é simples: você define um tempo mínimo de inatividade (ex.: 60 segundos) e a API fica monitorando até detectar o evento.

Quando isso acontece, ela dispara uma mudança de estado. É mais eficiente que usar timers com setTimeout() porque ela acompanha o comportamento real do usuário e do sistema.

O que ela monitora (userState e screenState)

A Idle Detection API acompanha dois estados principais:

Isso permite criar lógicas muito mais inteligentes.
Exemplo:

if (userState === "idle" && screenState === "locked") {
  // desconectar usuário por segurança
}

E o mínimo recomendado pela API para detecção é 1 minuto:

{ threshold: 60_000 } // 60s de inatividade

Esse nível de controle abre possibilidades legais para apps web que dependem da presença do usuário.

Permissões necessárias no navegador

A Idle Detection API não funciona sem autorização do usuário. Isso garante privacidade e evita abusos, afinal, detectar comportamento é algo sensível.

Antes de usar, você precisa solicitar permissão do usuário:

const permission = await IdleDetector.requestPermission();

if (permission !== "granted") {
  console.log("Permissão negada");
}

Quando a permissão aparece, parece aquela janelinha parecida com:

• “Deseja permitir notificações?”
• “Permitir acesso ao microfone?”

Só que, no caso, é para detectar inatividade.

Por que isso importa?

• Transparência
• Segurança
• UX mais justa

O pedido deve ser feito no momento certo — idealmente após uma ação do usuário (ex.: clicar em um botão).

Suporte dos navegadores

Nem todo navegador já implementa a Idle Detection API. Hoje, ela funciona principalmente nas versões mais recentes do Chrome e derivados (Brave, Edge, Opera).

Resumo rápido:

Para consultar suporte atualizado sempre podemos utilizar o site Can I Use

É sempre bom colocar um fallback simples, como exibir uma mensagem caso o recurso não exista:

if (!("IdleDetector" in window)) {
  alert("Seu navegador ainda não suporta Idle Detection API");
}

Criando um projeto com Idle Detection API

Agora que você já sabe o que a Idle Detection API faz e por que ela é tão útil no JavaScript, vamos criar um projeto simples para testar na prática. A ideia aqui é montar uma página com um botão que ativa o detector e um campo que mostra o status do usuário — ativo, inativo, tela bloqueada, desbloqueada, etc.

Nada complexo. Apenas o essencial para ver a API funcionando no navegador e entender como ela reage ao comportamento do usuário.

Estrutura do HTML

Vamos começar criando um arquivo index.html.
Ele será responsável por:

• Exibir um botão para ativar o detector
• Mostrar o status de atividade do usuário
• Carregar nosso script JavaScript

Exemplo básico:

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>JavaScript Detecta Inatividade com Idle Detection API</title>

    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link
      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap"
      rel="stylesheet"
    />

    <link rel="stylesheet" href="style.css" />
  </head>

  <body>
    <div class="container">
      <h1>JavaScript Detecta Inatividade com Idle Detection API</h1>

      <p>
        A API <strong>Idle Detection</strong> permite que o navegador detecte
        quando o usuário está inativo ou ausente, com base na atividade do
        sistema e do input (mouse/teclado).
      </p>

      <p>
        Isso abre portas para recursos como: logouts automáticos, pausar vídeos,
        enviar lembretes e muito mais!
      </p>

      <button id="start">Ativar Detector de Inatividade</button>

      <div id="status" class="status">
        Aguardando inicialização do Detector.
      </div>
    </div>

    <script src="script.js"></script>
  </body>
</html>

Por que assim?
Queremos uma UI clara e enxuta para focar no comportamento da Idle Detection API no JavaScript, sem distrações.

Estilização simples com CSS

Pode ser minimalista — o objetivo aqui é organização visual.
Crie um arquivo style.css:

* {
  box-sizing: border-box;
  padding: 0;
  margin: 0;
}

body {
  min-height: 100svh;
  display: grid;
  place-items: center;
  background: radial-gradient(1200px 600px at 0% 0%, #121d46 0, #0b1020 55%),
    radial-gradient(900px 400px at 100% 100%, #0e1536 0, transparent 60%);
  color: #eaf0ff;
  font: 500 16px/1.5 Inter, system-ui, -apple-system, Segoe UI, Roboto, Arial;
  padding: 32px;
}

.container {
  max-width: 640px;
  width: 100%;
  background: #0f1836;
  border: 1px solid #24316b;
  border-radius: 16px;
  padding: 24px;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.35);
}

h1 {
  font-size: 24px;
  margin-bottom: 16px;
}

p {
  margin-bottom: 16px;
  color: #a9b4d6;
}

pre {
  background: #0a1433;
  border: 1px solid #22306a;
  border-radius: 12px;
  padding: 16px;
  color: #dfe8ff;
  overflow-x: auto;
  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
  font-size: 14px;
  margin-top: 16px;
}

.status {
  margin-top: 20px;
  font-weight: 600;
  font-size: 18px;
  color: #7aa2ff;
}

button {
  background: #2e4ba5;
  color: #fff;
  padding: 16px 20px;
  border-radius: 8px;
  font-weight: 600;
  flex: 1;
  text-align: center;
  margin-top: 25px;
  border: none;
  cursor: pointer;
  transition: background ease 200ms;
}

button:hover {
  background: #233a7e;
}

Isso centraliza tudo e melhora a experiência enquanto você testa o userState e screenState.

Dica: durante desenvolvimento, mantenha o estilo leve. Assim você foca no comportamento da API.

Importando o script JavaScript

Por fim, conecte o arquivo JavaScript (script.js), onde vamos configurar a Idle Detection API com JavaScript.

Verifique se o script já foi incluído no final do HTML:

<script src="script.js"></script>

Isso garante que o DOM já tenha carregado quando seu código rodar — evitando erros como “element not found”.

Para organizar o projeto:

📁 idle-detection-demo
 ├ index.html
 ├ style.css
 └ script.js

Por que dessa forma?

• Facilita manutenção
• Código mais limpo
• Separação clara entre HTML, CSS e JS

Na próxima etapa, vamos inserir o código completo da Idle Detection API no arquivo script.js e testar a detecção de inatividade em tempo real.

Full Stack Impressionador

Essa é uma trilha de especialização que vai te tornar um verdadeiro Desenvolvedor Web Full Stack, dominando todas as principais tecnologias usadas tanto para o Front End quanto para o Backend e ainda para Mobile, construindo projetos práticos e exercícios aplicados à realidade das empresas. Tudo o que você precisa para se tornar um Desenvolvedor Full Stack em um único lugar.

Começar agora

Código completo com Idle Detection API no JavaScript

Chegou a hora de colocar a Idle Detection API em ação. Aqui vamos montar o script.js que faz seu navegador detectar quando o usuário está ativo, inativo, com a tela bloqueada ou desbloqueada — tudo em tempo real.

A lógica é simples e segue essa sequência:

1. Pegar elementos da página
2. Checar se o navegador suporta a API
3. Solicitar permissão ao usuário
4. Criar o detector
5. Monitorar mudanças de estado
6. Iniciar a detecção com o tempo desejado (ex.: 60 segundos)

Vamos pro passo a passo!

Variáveis e elementos da página

Primeiro, selecionamos o botão e o campo de status.
Isso permite atualizar o texto na tela quando o estado do usuário mudar.

const statusEl = document.getElementById("status");
const btn = document.getElementById("start");

Por quê?
Queremos mostrar ao usuário o que está acontecendo: ativo, inativo, tela bloqueada etc.
Sem isso, nada aparece visualmente.

Dica: sempre comece pegando os elementos que você vai atualizar no DOM.

Verificando suporte do navegador

Nem todos os navegadores suportam a Idle Detection API ainda. Antes de tudo, validamos isso:

btn.addEventListener("click", async () => {
  if (!("IdleDetector" in window)) {
    statusEl.textContent = "API não suportada neste navegador.";
    return;
  }

Por que isso importa?

Evita erros e melhora a experiência. Se o navegador do usuário não tiver suporte, você pode sugerir Chrome/Edge ou mostrar um aviso amigável.

Solicitando permissão ao usuário

A Idle Detection API exige permissão explícita — privacidade primeiro.

btn.addEventListener("click", async () => {
  if (!("IdleDetector" in window)) {
    statusEl.textContent = "API não suportada neste navegador.";
    return;
  }

  try {
    const permission = await IdleDetector.requestPermission();

    if (permission !== "granted") {
      statusEl.textContent = "Permissão negada.";
      return;
    }

Se o usuário negar, encerramos o fluxo. Sem permissão, sem detecção.

Lembre: essa permissão precisa ser pedida após uma ação do usuário (como clicar no botão).

Detectando mudanças de estado

Agora criamos o detector e escutamos os eventos de mudança.

btn.addEventListener("click", async () => {
  if (!("IdleDetector" in window)) {
    statusEl.textContent = "API não suportada neste navegador.";
    return;
  }

  try {
    const permission = await IdleDetector.requestPermission();

    if (permission !== "granted") {
      statusEl.textContent = "Permissão negada.";
      return;
    }

    const detector = new IdleDetector();

    detector.addEventListener("change", () => {
      const userState = detector.userState;
      const screenState = detector.screenState;

      statusEl.textContent = `Usuário: ${userState} | Tela: ${screenState}`;

      if (userState === "idle") window.alert("Usuário ficou inativo!");
    });

Aqui temos a mágica:

Se o usuário ficar idle → mostramos alerta e atualizamos o status.

userState pode ser active ou idle

screenState pode ser locked ou unlocked

Iniciando o detector com tempo de inatividade

Só criar não basta — precisamos ativar.

btn.addEventListener("click", async () => {
  if (!("IdleDetector" in window)) {
    statusEl.textContent = "API não suportada neste navegador.";
    return;
  }

  try {
    const permission = await IdleDetector.requestPermission();

    if (permission !== "granted") {
      statusEl.textContent = "Permissão negada.";
      return;
    }

    const detector = new IdleDetector();

    detector.addEventListener("change", () => {
      const userState = detector.userState;
      const screenState = detector.screenState;

      statusEl.textContent = `Usuário: ${userState} | Tela: ${screenState}`;

      if (userState === "idle") window.alert("Usuário ficou inativo!");
    });

    await detector.start({
      threshold: 60_000, // 1 minuto
    });

threshold = tempo mínimo parado

O recomendado é 1 minuto (60.000ms).

Fórmula mental:
1s = 1000ms
60s = 60.000ms

Se quiser testar mais rápido enquanto desenvolve, pode usar algo menor (ex.: 5000).

Exibindo status e enviando alertas

Com tudo rodando, avisamos o usuário ao ativar:

btn.addEventListener("click", async () => {
  if (!("IdleDetector" in window)) {
    statusEl.textContent = "API não suportada neste navegador.";
    return;
  }

  try {
    const permission = await IdleDetector.requestPermission();

    if (permission !== "granted") {
      statusEl.textContent = "Permissão negada.";
      return;
    }

    const detector = new IdleDetector();

    detector.addEventListener("change", () => {
      const userState = detector.userState;
      const screenState = detector.screenState;

      statusEl.textContent = `Usuário: ${userState} | Tela: ${screenState}`;

      if (userState === "idle") window.alert("Usuário ficou inativo!");
    });

    await detector.start({
      threshold: 60_000, // 1 minuto
    });

    statusEl.textContent = "Detector iniciado. Aguarde inatividade...";
  } catch (err) {
    statusEl.textContent = `Erro: ${err.message}`;
  }
});

Resultado final?

Seu navegador agora entende quando a pessoa está ativa, inativa ou com tela bloqueada — tudo usando Idle Detection API no JavaScript.

Você abre caminho para funcionalidades como:

• Logout automático
• Pausa de vídeos
• Notificações
• Sistemas mais seguros
• Experiência mais fluida

Casos de uso com a Idle Detection API

A Idle Detection API abre várias possibilidades para deixar sua aplicação web mais inteligente, segura e responsiva ao comportamento real do usuário.

A ideia é simples: se a pessoa parou de interagir, sua aplicação toma uma ação sozinha. Isso melhora experiência, aumenta segurança e dá um toque profissional ao seu projeto front-end.

Abaixo vão alguns exemplos reais para você aplicar agora.

Logout automático por segurança

Sabe quando você entra no site do seu banco e, depois de um tempo sem mexer, ele te desloga automaticamente? Agora dá pra fazer isso só com JavaScript usando a Idle Detection API.

Por que usar:
Protege dados sensíveis e evita acessos indevidos.

Como funciona:

if (userState === "idle" && threshold >= 60_000) {
  logoutUser();
}

Recomendação: pelo menos 1 minuto antes de deslogar automaticamente.

Pausar vídeos ou conteúdo

Perfeito para plataformas de vídeo, cursos online e players customizados. Se o usuário ficar inativo, pause para não perder conteúdo.

if (userState === "idle") {
  video.pause();
}

Isso evita que o aluno deixe a aula rolando sem assistir — bem útil pra plataformas educacionais.

Exibir pop-up ou lembrete

Ótimo para apps de saúde, produtividade, foco e estudos.

Exemplo: usuário ficou 90 segundos parado → mostrar lembrete:

if (userState === "idle") {
  alert("Pausa rápida? Volta aí pra continuar :)");
}

Use de forma amigável e humana — ninguém gosta de lembrete agressivo.

Monitoramento de usuários ativos em apps web

Em dashboards, ERPs, CRMs e sistemas internos, saber quem está ativo em tempo real pode ser útil.

Exemplo: sistema mostra quantos usuários estão ativos neste momento.

if (userState === "active") {
  markUserOnline();
} else {
  markUserIdle();
}

Ideal para equipes remotas, help desks e plataformas de atendimento.

Boas práticas para usar Idle Detection API

Essa API é poderosa, mas precisa ser usada com cuidado. O objetivo é ajudar o usuário, não invadir sua privacidade ou atrapalhar a experiência.

Solicitar permissão no momento certo

Nunca peça permissão na hora que o site carrega.
Aguarde o usuário clicar em um botão, como “Ativar detecção”.

Isso dá controle e evita rejeições.

startBtn.addEventListener("click", initIdleDetector);

Evitar pop-ups excessivos

Alertas demais irritam o usuário e viram anti-UX. Use com contexto.

Em vez disso, prefira:

• Toasts
• Mensagens suaves
• Atualizar o status na tela
• Desativar função e mostrar aviso discreto

Menos interrupção = mais experiência.

Complementar com outras verificações

Combine a Idle Detection API com:

• visibilitychange (aba ativa?)
• timers graduais
• eventos do mouse/teclado quando necessário

document.addEventListener("visibilitychange", () => {
  if (document.hidden) console.log("Aba oculta");
});

Isso dá precisão extra e cobre comportamentos diferentes.

Documentação e referências oficiais

Quer se aprofundar mais? Confira a documentação oficial dessa API:

Documentação Google - Guia oficial com exemplos e explicações.

MDN Web Docs - Referência mais completa e detalhada.

Sempre que tiver dúvida sobre sintaxe, compatibilidade ou propriedades, comece pela MDN.

Conclusão

A Idle Detection API traz um novo nível de inteligência para aplicações web, permitindo detectar inatividade do usuário no navegador e reagir de forma segura e eficiente.

Ao longo deste artigo, você viu como ela funciona, como implementar no JavaScript, casos reais e boas práticas para aplicar em sistemas modernos, desde logouts automáticos até alertas e pausas inteligentes em conteúdo.

Agora você já tem uma base sólida para usar esse recurso em projetos reais e elevar a experiência do usuário no seu front-end.

Se você quer dominar de verdade o desenvolvimento web e criar aplicações completas, seguras e modernas como as que vimos aqui, conheça nosso curso completo Full Stack Impressionador.

Caso prefira esse conteúdo no formato de vídeo-aula, assista ao vídeo abaixo ou acesse o nosso canal do YouTube!

O que você aprende neste vídeo

Resposta rápida: Nesta aula, o Diego ensina a Idle Detection API do JavaScript, que detecta quando o usuário fica inativo (parado, sem mexer o mouse ou o teclado). Ele mostra como verificar se o navegador suporta a API, pedir a permissão ao usuário e disparar uma ação quando ele fica ocioso (ex.: um alerta), útil para pausar tarefas ou avisar quando a pessoa se ausenta.

Neste vídeo (7 min):

• 0:00 - O que é a Idle Detection API: detectar quando o usuário fica inativo.
• 3:00 - Verificar se o navegador suporta a API (senão, avisar).
• 4:00 - Pedir a permissão do usuário para monitorar a inatividade.
• 5:00 - Disparar uma ação quando ele fica ocioso (ex.: um alerta).
• 6:00 - Consultar a documentação da API para se aprofundar.

FAQ — Idle Detection API no JavaScript

Hashtag Treinamentos

Para acessar publicações de Full Stack, clique aqui!

Posts mais recentes de Full Stack

• 
  LESS CSS: Guia Completo do Pré-processador (2026)8 de maio de 2026
  LESS CSS é um pré-processador que adiciona variáveis, mixins, nesting e operações matemáticas ao CSS. Aprenda a configurar e usar com projeto prático.
• 
  Variáveis no CSS (CSS Variables): Como Usar de Forma Profissional29 de dezembro de 2025
  Você sabe o que são Variáveis no CSS (CSS Variables)? Aprenda como usar técnicas que vão transformar a forma como você escreve variáveis CSS.
• 
  Try Catch no JavaScript: Programação Defensiva na Prática27 de novembro de 2025
  Aprenda a usar try catch no JavaScript e melhore a sua programação defensiva!

Posts mais recentes da Hashtag Treinamentos

• 
  Planilha de Controle de Notas Fiscais no Excel [Grátis]2 de outubro de 2026
  Baixe a planilha de controle de notas fiscais no Excel grátis: calcule ISS e retenções, veja o que está em aberto e gere a cobrança de cada nota de serviço.
• 
  Qual IA usar na empresa: ChatGPT, Claude ou Perplexity?2 de outubro de 2026
  Qual IA usar na empresa: veja as diferenças entre ChatGPT, Claude e Perplexity e quando cada um rende mais em cada área da sua equipe.
• 
  Apostilas Gratuitas em PDF: Excel, Power BI, Python e IA30 de setembro de 2026
  Baixe apostilas gratuitas em PDF de Excel, Power BI, Python, Claude e agentes de IA, com exercícios e gabarito. Escolha a sua e comece hoje.