Kavchat by maxsave
Menu de guias

iOS

O pacote Swift do Kavchat adiciona ao seu app iOS um bot de atendimento baseado em roteiros, com componentes SwiftUI e UIKit. As respostas são previsíveis e continuam funcionando mesmo sem internet, com base na última versão publicada. Requer iOS 15 ou superior.

O pacote tem dois produtos: KavchatEngine, a versão em Swift do mecanismo de conversa, sem UIKit, e Kavchat, com comunicação de rede, cache no dispositivo e interface: KavchatChatView (SwiftUI), KavchatLauncher e KavchatViewController (UIKit).

Instalação

Com o Swift Package Manager no Xcode: selecione File > Add Package Dependencies e informe o endereço do repositório:

Package URL
https://bitbucket.org/maxsave/kavchat-ios.git

Ou no arquivo Package.swift:

Package.swift
.package(url: "https://bitbucket.org/maxsave/kavchat-ios.git", from: "0.0.11"),
// ...
.product(name: "Kavchat", package: "kavchat-ios"),

O SDK tem código aberto, sob a licença MIT: bitbucket.org/maxsave/kavchat-ios.

Configuração

Chame configure uma única vez, o mais cedo possível, por exemplo no init de App ou em application(_:didFinishLaunchingWithOptions:):

Swift
import Kavchat

Kavchat.configure(publicKey: "pk_live_...")            // the public key from the dashboard
// Optional:
// Kavchat.configure(publicKey: "pk_live_...", apiBase: "https://api.kavchat.com", locale: "he")

A chave pública pode ser incluída no app. A chave secreta (sk_live_...) nunca deve ser incluída.

SwiftUI

Um botão flutuante no canto definido no painel, que abre o chat em uma janela (sheet):

SwiftUI
ContentView()
    .kavchatLauncher()

Você também pode posicionar o botão por conta própria ou incorporar o chat em uma tela sua:

SwiftUI
KavchatLauncher()
KavchatChatView()                                      // full chat, no close button
KavchatChatView(onClose: { showChat = false })         // with a close button

Abra e feche a janela do botão flutuante pelo código com Kavchat.open() e Kavchat.close().

UIKit

UIKit
Kavchat.present(from: self)                            // modal, with a close button
// or
let chat = KavchatViewController(showsCloseButton: false)
navigationController?.pushViewController(chat, animated: true)

Token de identidade

Identifique um usuário conectado com um JWT assinado pelo seu servidor com a chave secreta (veja Identificação de usuários). O token é enviado no cabeçalho Authorization: Bearer <token>. Um usuário identificado pode ver versões restritas a usuários de teste e enviar o formulário de contato sem e-mail ou telefone.

Swift
Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // after logout

A troca de usuário recarrega a versão e inicia uma nova conversa, para que a conversa de um usuário não apareça para outro.

Telas do app: onScreen

Um botão do tipo screen no roteiro solicita que o app abra uma de suas telas. A janela do chat é fechada antes, para que a tela fique visível:

Swift
Kavchat.onScreen = { screen, targetId in
    router.open(screen, id: targetId)                  // e.g. "orders", "42"
}

Sem um handler, esses botões não fazem nada. Botões link abrem apenas links https e tel. Para análise de dados, Kavchat.onEvent informa os eventos ready, unavailable, open, close, effect e ticket.

Lista de telas no editor

Declare uma única vez as telas que o app pode abrir em Kavchat.configure(..., screens:). O SDK envia a lista ao Kavchat automaticamente, e o editor de roteiros oferece essas telas em uma lista suspensa com seus nomes, no lugar de um campo de texto livre. O editor também solicita um identificador de item quando a tela precisa dele e avisa quando um botão aponta para uma tela que não foi declarada. Ninguém precisa digitar a lista de telas manualmente no painel.

Swift
Kavchat.configure(publicKey: "pk_live_...", screens: [
    KavchatScreen(id: "orders", label: "My orders"),
    KavchatScreen(id: "product", label: "Product page", needsTarget: true),  // needs a targetId
])
// or later: Kavchat.registerScreens([...])
  • id é o valor recebido por onScreen: letras latinas, números, _, . e -, até 40 caracteres. label é o nome que o administrador vê, até 60 caracteres. Até 100 telas. Entradas inválidas e identificadores duplicados são descartados.
  • needsTarget: o botão também carrega um identificador de item (por exemplo, o identificador de um produto), recebido por onScreen como targetId.
  • A lista é enviada em segundo plano depois que a versão é carregada, apenas quando há alterações ou uma vez por semana. Falhas não são exibidas, e o envio é tentado novamente na próxima abertura do app. O usuário não vê nada.
  • As telas registradas aparecem no painel em Bot, Configurações, "Telas do app", com as plataformas que informaram cada tela. Uma tela removida do app pode ser excluída ali.

Cores

As cores vêm do painel (primaryColor). O texto sobre a cor da marca fica branco ou quase preto, conforme o contraste WCAG. Cores claras demais para texto sobre fundo branco são substituídas por quase preto em links e botões. O nome do bot, o subtítulo, a imagem e o lado do botão flutuante (start ou end) também vêm do painel, por isso podem mudar sem atualizar o app.

O selo "Tecnologia Kavchat by maxsave" aparece em todos os planos, com um link para kavchat.com. No Premium, você pode ocultá-lo nas configurações do bot.

Idiomas e RTL

  • O idioma da interface é o locale passado para configure. Se não for informado, será usado o idioma do dispositivo, se houver tradução (he, en, ar, ru, es, fr, de, pt, it, tr). Depois, o idioma do roteiro e, por último, o inglês.
  • A correspondência com o roteiro sempre usa o idioma do roteiro (palavras comuns que são ignoradas e prefixos em hebraico e árabe).
  • Em hebraico e árabe, o layoutDirection de todo o chat é da direita para a esquerda. Nada é invertido manualmente: se você envolver os componentes em outros elementos, use leading e trailing.

Respostas de IA (Premium)

Não há nada para configurar no app. Ao ativar as respostas de IA no painel de administração (com sua própria chave de um provedor de IA), uma pergunta que nenhum roteiro responde é enviada ao Kavchat. Durante a espera, de até 20 segundos, o chat mostra que o bot está digitando. A resposta aparece como texto simples, com uma pequena indicação "Resposta de IA" no idioma da interface. Abaixo dela aparecem um botão para um assunto relacionado, se houver, e o botão "Falar com a equipe".

Se não houver resposta, ou se a solicitação falhar, demorar demais ou ultrapassar o limite (10 respostas por conversa a cada 15 minutos), o chat exibe a mensagem padrão "Não encontrei uma resposta". A pergunta continua aparecendo no relatório de perguntas sem resposta, e as respostas de IA ficam na conversa salva como qualquer outra mensagem.

Chat com atendente

Não é preciso configurar nada no app. Ao ativar o chat com atendentes no painel de administração, o chat do app funciona exatamente como o widget do site.

  • A opção só aparece quando o chat com atendentes está ativado na versão publicada. Quando o bot mostra "Falar com a equipe", o SDK verifica se há um atendente disponível. O resultado fica em cache por 30 segundos. Se houver alguém disponível, o botão "Falar com atendente" aparece antes dessa opção. Caso contrário, aparece apenas o formulário de contato. Acima dele, uma linha curta explica o motivo: fora do horário de atendimento (incluindo o horário de retorno) ou todos os atendentes estão ocupados.
  • Antes da conversa, é preciso preencher um formulário curto: nome, e-mail ou telefone, departamento (apenas quando há mais de um departamento aberto) e uma primeira mensagem (opcional). Visitantes precisam informar e-mail ou telefone. Usuários identificados por token de identidade não precisam informar nenhum dos dois. Se não houver mais atendentes disponíveis no momento do envio, o formulário de contato é aberto com os dados já preenchidos.
  • Durante a espera, aparecem o tempo restante até que a conversa vire um chamado e o botão "Deixar uma mensagem em vez de esperar". O tempo de espera é definido no painel de administração, com padrão de 2 minutos. É possível escrever durante a espera, e o atendente verá as mensagens. Se nenhum atendente ficar disponível a tempo, a conversa é salva como um chamado comum e o número do chamado é exibido.
  • Durante a conversa, aparecem o nome do atendente, um aviso quando um atendente entra (inclusive após uma transferência), um indicador de digitação e um botão para encerrar a conversa. As mensagens contêm apenas texto simples, até 2.000 caracteres, sem links. Uma mensagem que ainda não chegou ao servidor aparece como "Enviando...". Se o envio falhar várias vezes, você pode tocar na mensagem para tentar novamente. Uma nova tentativa não cria uma mensagem duplicada.
  • Após cada desconexão, o SDK espera um pouco, recupera o que foi perdido e se reconecta. O tempo de espera aumenta gradualmente. As mensagens sempre aparecem na ordem e sem duplicações. Se a conexão contínua não funcionar (por exemplo, atrás de um proxy corporativo), o SDK passa temporariamente a consultar o servidor em intervalos.
  • Quando o app vai para segundo plano, a conexão é fechada. Ao voltar ao app, o SDK recupera o que foi perdido e se reconecta. Uma conversa aberta continua mesmo depois de fechar e reabrir o app, desde que não tenham passado 12 horas.
  • Esta versão não tem notificações push. As mensagens chegam apenas enquanto o app está aberto. Uma resposta enviada enquanto o app estava em segundo plano aparece assim que você volta a ele.
  • As credenciais de acesso à conversa ficam apenas na memória e no Keychain do dispositivo. Elas não são armazenadas em UserDefaults, em uma URL ou em logs. São excluídas quando a conversa termina, vira um chamado ou expira, e também ao trocar de usuário com setUser.

Você pode usar Kavchat.shared.livePage para informar ao atendente de qual tela o usuário veio.

Perguntas, condições e leads

Não é preciso configurar nada no app. Um roteiro pode pedir dados (nome, telefone, e-mail, número ou texto livre), escolher como continuar com base nas informações conhecidas e enviar um lead.

  • Teclado adequado: Quando o bot espera uma resposta, o campo de texto mostra um teclado de telefone, e-mail ou números. Em perguntas de nome, o teclado coloca a primeira letra de cada palavra em maiúscula. Se a resposta for inválida, o bot responde com uma mensagem curta no idioma do chat e o campo é destacado. Perguntas opcionais mostram o botão "Pular". Digitar "Cancelar", em qualquer idioma compatível, sai da pergunta.
  • Telefone: Números sem + usam o país padrão do espaço de trabalho, definido nas configurações do painel de administração.
  • Lead: Uma etapa de lead mostra o texto de consentimento com os botões "Enviar" e "Não, obrigado" e, em seguida, a mensagem de confirmação. O lead entra na fila do dispositivo e é enviado ao servidor. Sem conexão com a internet ou com o servidor indisponível, o envio é tentado novamente, inclusive na próxima abertura do app e após reload(). O servidor ignora duplicações.
  • Preenchimento automático: O formulário de contato e o formulário de solicitação de atendimento são preenchidos com o nome, o e-mail e o telefone coletados. Todos os valores coletados são anexados ao chamado ou à solicitação de atendimento. As perguntas antes de uma conversa com atendente (Premium) são feitas antes da conexão.
  • Token de identidade: Ao usar setUser, os campos name, email e phone do token preenchem as respostas às perguntas correspondentes, e o bot pula essas perguntas.
  • Tela atual: As condições podem verificar a tela atual. Defina Kavchat.shared.livePage (por exemplo, "checkout").

Os valores coletados são dados pessoais. Eles permanecem na conversa salva no dispositivo e são enviados apenas para leads, chamados e conversas com atendentes, nunca para relatórios.

Uso sem internet e cache

A última versão fica salva em UserDefaults com seu ETag e é revalidada com If-None-Match (304) a cada abertura do app. Sem internet, a cópia salva é usada e um aviso informa isso. Quando o bot está desativado, restrito a usuários de teste ou com a cota esgotada, nada é exibido. Uma conversa aberta fica salva por até 30 minutos de inatividade, para que sair do chat ou do app não a reinicie. O percurso da conversa é informado dois segundos após a última ação e imediatamente quando o app vai para segundo plano.