Problemas Comuns

Problemas de Inicialização

⚠️ Engine incorreta - Sistema não funciona

Sintoma: O adapter parece inicializar corretamente, mas o reconhecimento de voz não funciona ou apresenta comportamento inesperado.

Causa: O parâmetro engine não foi especificado ou está com valor incorreto. Sem este parâmetro, o sistema usa a engine padrão ALS que não é compatível com o Iara Desktop Adapter.

Solução:

// ❌ INCORRETO - Sem especificar engine (usará ALS por padrão)
recognition.init({
  userId: 'meu@email.com',
  apiToken: 'seu-token'
  // engine não especificada - ERRO!
});

// ❌ INCORRETO - Engine errada
recognition.init({
  userId: 'meu@email.com',
  apiToken: 'seu-token',
  engine: 'ALS'  // Engine incompatível!
});

// ✅ CORRETO - Engine Iara Desktop
recognition.init({
  userId: 'meu@email.com',
  apiToken: 'seu-token',
  engine: 'Iara Desktop',  // ⚠️ OBRIGATÓRIO para o adapter funcionar!
  lang: 'pt-BR'
}).done(function() {
  const adapter = new IaraSyncfusionAdapter(editor, recognition);
});

Importante

SEMPRE especifique engine: 'Iara Desktop' ao usar o Iara Syncfusion Adapter. Este parâmetro é obrigatório e não pode ser omitido.

Erro: “Recognition not ready”

Sintoma: Erro ao criar o adapter informando que o recognition não está pronto.

Causa: O adapter foi criado antes do recognition completar a inicialização.

Solução:

// ❌ Incorreto - não aguarda inicialização
const recognition = new IaraSpeechRecognition();
const adapter = new IaraSyncfusionAdapter(editor, recognition);

// ✅ Correto - aguarda inicialização
const recognition = new IaraSpeechRecognition();
recognition.init({
  userId: 'meu@email.com',
  apiToken: 'seu-token'
  engine: 'Iara Desktop',       // Verifique se está correto
}).done(function() {
  // Só criar adapter após done()
  const adapter = new IaraSyncfusionAdapter(editor, recognition);
});

Erro: “Invalid credentials”

Sintoma: Falha na inicialização com mensagem de credenciais inválidas.

Possíveis causas:

• API Token incorreto
• User ID incorreto
• Região incorreta
• Credenciais expiradas

Solução:

1. Verifique suas credenciais no Portal Iara
2. Confirme que está usando a região correta (south-america ou europe)
3. Tente gerar um novo token se o atual expirou

recognition.init({
  userId: 'seu@email.com',      // Verifique se está correto
  apiToken: 'seu-token-aqui',   // Verifique se está correto
  engine: 'Iara Desktop',       // Verifique se está correto
  region: 'south-america'       // Verifique a região
}).done(function() {
  console.log('✅ Credenciais válidas!');
}).fail(function(error) {
  console.error('❌ Erro:', error.message);
});

Problemas com Assistente de IA

Assistente não aparece

Sintoma: O botão do assistente não aparece ao selecionar texto.

Verificações:

1. Assistente está habilitado?

const config = {
  assistant: {
    enabled: true  // ✅ Deve estar true
  }
};

2. Container existe no DOM?

assistant: {
  draggable: {
    containerId: '#existing-container-id'  // ✅ ID deve existir
  }
}

// Verificar se container existe
const container = document.getElementById('existing-container-id');
if (!container) {
  console.error('❌ Container não encontrado');
}

3. Componentes Iara carregados?

<!-- Necessário para o assistente -->
<script src="https://dev.components.iarahealth.com/components-lib.js" type="module"></script>

Sugestões da IA não aparecem

Sintoma: O assistente abre mas não gera sugestões.

Possíveis causas:

• Sem conexão com internet
• Erro na API da Iara

Solução:

1. Verifique a conexão com internet
2. Verifique o console do navegador para erros
3. Tente novamente após alguns segundos

Problemas com Reconhecimento de Voz

Microfone não funciona

Sintoma: Ao clicar no botão de microfone, nada acontece.

Verificações:

1. Permissão do navegador

   • Verifique se o navegador tem permissão para acessar o microfone
   • Chrome: Ícone de cadeado na barra de endereço → Configurações do site
   • Firefox: Ícone de cadeado → Permissões

2. HTTPS obrigatório

   • O reconhecimento de voz só funciona em HTTPS (exceto localhost)
   • Certifique-se de que sua aplicação está em HTTPS

3. Microfone conectado

   • Verifique se há um microfone conectado ao computador
   • Teste o microfone em outras aplicações

Reconhecimento impreciso

Sintoma: O texto reconhecido está incorreto ou com muitos erros.

Soluções:

1. Melhore a qualidade do áudio

   • Use um microfone de qualidade
   • Reduza ruído ambiente
   • Fale claramente e em ritmo normal

2. Configure o idioma correto

recognition.init({
  lang: 'pt-BR'  // Certifique-se de usar o idioma correto
});

3. Use VAD (Voice Activity Detection)

recognition.init({
  useVAD: true  // Detecta quando o usuário começa e para de falar
});

Problemas de Performance

Editor lento após integração

Sintoma: O editor fica lento depois de integrar o adapter.

Soluções:

1. Desabilite funcionalidades não usadas

{
  assistant: { enabled: false },  // Se não usar IA
  highlightInference: false,      // Se não precisar de destaque
  saveReport: false               // Se não precisar de auto-save
}

2. Otimize callbacks

// ❌ Evite operações pesadas em callbacks
adapter.onIaraCommand = function(command) {
  // Operação pesada aqui pode travar a UI
  heavyOperation();
};

// ✅ Use debounce ou async
adapter.onIaraCommand = debounce(function(command) {
  heavyOperation();
}, 300);

Alto uso de memória

Sintoma: A aplicação consome muita memória.

Soluções:

1. Destrua o adapter quando não precisar mais

// Ao desmontar componente ou fechar editor
if (adapter) {
  adapter.destroy();
  adapter = null;
}

2. Limite o histórico de undo/redo

editor.documentEditor.editorHistory.undoLimit = 50;  // Padrão é 300

Problemas de Compatibilidade

Erro com versão do Syncfusion

Sintoma: Erros relacionados a métodos ou propriedades não encontrados.

Solução:

Verifique se está usando uma versão compatível do Syncfusion:

{
  "@syncfusion/ej2-documenteditor": ">=20.0.0"
}

Se estiver usando uma versão muito antiga, considere atualizar.

Conflitos com outros plugins

Sintoma: Erros ao usar o adapter junto com outros plugins do Syncfusion.

Solução:

1. Carregue o adapter por último
2. Verifique se não há conflitos de namespace
3. Use replaceToolbar: false para manter compatibilidade

Problemas de Build

Erro ao fazer build da aplicação

Sintoma: Erros de TypeScript ou bundler ao fazer build.

Soluções:

1. TypeScript - Tipos não encontrados

tsconfig.json

{
  "compilerOptions": {
    "types": ["@iarastt/adapters"]
  }
}

2. Webpack - Módulo não encontrado

webpack.config.js

module.exports = {
  resolve: {
    extensions: ['.ts', '.js', '.mjs']
  }
};

3. Vite - Otimização de dependências

vite.config.js

export default {
  optimizeDeps: {
    include: ['@iarastt/adapters']
  }
};

Ainda com problemas?

Se você ainda está enfrentando problemas:

1. Verifique a documentação completa

   • Guia de Instalação
   • Quick Start
   • Configuração Avançada

2. Consulte exemplos

   • Exemplos práticos

3. Entre em contato

   • Email: contato@iarahealth.com
   • Documentação IaraSpeechRecognition: developers.iarahealth.com