Integração com E-Reader

O Bookworm se integra com e-readers e aplicativos de leitura para manter seu progresso sincronizado. Atualmente, o suporte nativo é disponível para o KOReader via protocolo KOSync. Outros aplicativos podem se integrar via o endpoint de webhook genérico.

KOReader (Suporte Nativo)

O KOReader é um aplicativo de leitura gratuito e de código aberto, disponível para Kindle, Kobo, PocketBook, Android e outros dispositivos. O Bookworm implementa o protocolo KOSync, permitindo que o KOReader sincronize o progresso de leitura diretamente.

Como Funciona

1. O KOReader envia atualizações de progresso para o Bookworm enquanto você lê.
2. O Bookworm associa o livro a um da sua biblioteca (por título e autor).
3. Seu progresso de leitura e sessões são atualizados automaticamente.

Configuração

1. Gerar uma Chave de API

1. Vá em Configurações → Integrações.
2. Em Integração com E-Reader, clique em Gerar Chave de API.
3. Copie a chave gerada — você precisará dela para o KOReader.

Premium

Contas gratuitas têm direito a 1 chave de API. Contas premium têm chaves ilimitadas (útil se você tem múltiplos dispositivos).

2. Configurar o KOReader

No KOReader, vá em Settings → Cloud storage → Progress sync → Custom server e insira:

• Server URL: https://api.bookwormtracker.com/integrations/kosync
• Username: Seu email do Bookworm
• Password: A chave de API que você gerou

3. Associar Livros

Quando o KOReader sincroniza um livro que o Bookworm não reconhece, ele aparece como um livro não associado:

1. Você verá um alerta no seu Painel.
2. Clique para ver os livros não associados.
3. Para cada livro não associado, você pode:
   • Pesquisar na biblioteca para vincular a um livro existente
   • Pesquisar externamente para encontrar e importar o livro
   • Importar e vincular para adicionar o livro e vinculá-lo em um passo

Uma vez vinculado, futuras sincronizações se aplicam ao livro correto automaticamente.

Webhook Genérico

Para aplicativos de leitura que não suportam KOSync, o Bookworm oferece um endpoint de webhook genérico. Qualquer app ou ferramenta de automação pode enviar atualizações de progresso via uma chamada de API simples.

• Endpoint: POST https://api.bookwormtracker.com/integrations/webhook
• Autenticação: Bearer token (sua chave de API)

Isso é útil para integrações personalizadas ou ferramentas de automação como Tasker, Shortcuts ou n8n.

Google Play Livros (Limitado)

O Bookworm pode se conectar à sua conta do Google Play Livros para importar sua biblioteca. Devido a limitações na API do Google Books, esta integração é mais limitada que a sincronização do KOReader:

• Importação da biblioteca: O Bookworm pode descobrir livros da sua biblioteca do Google Play Livros e adicioná-los à sua biblioteca do Bookworm automaticamente.
• Posição de leitura: O Bookworm pode ler sua posição atual em um livro, mas os dados fornecidos pela API do Google são limitados e podem não ser sempre precisos.
• Sincronização manual: A API do Google não suporta notificações em tempo real. A sincronização deve ser acionada manualmente (por livro ou biblioteca inteira) ou acontece via uma verificação diária em segundo plano.

Configuração

1. Vá em Configurações → Integrações.
2. Clique em Conectar Google Play Livros.
3. Autorize o Bookworm a acessar seus dados de leitura.
4. Use o botão Sincronizar Biblioteca para importar seus livros, ou sincronize livros individuais na página de detalhes.

Dica

Para o rastreamento de progresso mais confiável, considere usar o KOReader no seu dispositivo. A integração com Google Play Livros funciona melhor como uma forma de importar sua biblioteca de livros para o Bookworm.

Configurações Recomendadas do KOReader

Para obter sessões de leitura e rastreamento de tempo mais precisos, configure o KOReader da seguinte forma:

Ativar Sincronização na Abertura e no Fechamento

No KOReader → Settings → Cloud storage → Progress sync, ative:

• Sync on book open — envia sua posição atual quando você começa a ler, criando um marcador de “início de sessão” no Bookworm.
• Sync on book close — envia sua posição quando você para de ler, criando um marcador de “fim de sessão”.

Ter ambas as opções ativas garante ao menos dois pontos de dados por sessão de leitura — o suficiente para estimar quanto tempo você leu e quantas páginas cobriu.

Dica

Dois syncs por sessão (abertura + fechamento) é o mínimo necessário para a estimativa de tempo de leitura. Quanto mais syncs dentro de uma janela de 15 minutos, mais precisa será a duração.

Ativar o Plugin de Estatísticas

O KOReader tem um plugin Statistics embutido que rastreia dados detalhados de leitura localmente no dispositivo:

1. No KOReader, vá em Menu → Ferramentas → Statistics.
2. Ative o plugin.

Isso não se conecta ao Bookworm, mas é útil para comparar o tempo de leitura do KOReader com o que o Bookworm calcula — prático para validar a precisão da sincronização.

Como Funciona o Tempo de Sessão

O Bookworm estima a duração de leitura a partir dos dados do KOSync usando uma janela deslizante de 15 minutos:

• Se dois ou mais syncs chegarem com menos de 15 minutos de intervalo, o Bookworm os agrupa em uma sessão e calcula a duração com base na velocidade de leitura.
• Se apenas um sync chegar (por exemplo, você leu offline e sincronizou apenas uma vez), o Bookworm registra as páginas mas não consegue estimar a duração — a sessão aparecerá com páginas mas sem tempo de leitura.
• Sessões sem duração estimada ainda contam na sua sequência e nas estatísticas de páginas.

Nota

O protocolo KOSync transmite apenas sua posição atual, não um cronômetro. A duração é sempre uma estimativa baseada na velocidade de leitura por página. Para tempos exatos, use o cronômetro de leitura integrado do Bookworm junto com o KOReader.

Detalhes da Sincronização

• KOReader: A sincronização acontece automaticamente quando você abre ou fecha um livro. Inclui número da página ou porcentagem, e o Bookworm cria sessões de leitura a partir das atualizações.
• Webhook: O progresso é sincronizado sempre que sua automação envia uma atualização.
• Google Play Livros: Sincronizado apenas quando você aciona manualmente ou via verificação diária em segundo plano. Importa livros como “Quero Ler” e atualiza o progresso dos livros associados quando dados de posição estão disponíveis.