Esse repositório contêm a documentação do SDK além de cópais dos pacotes binários para Android.
Esse é o SDK para a funcionalidade de comunicação via Chatbot.
O SDK foi desenvolvido em Kotlin e conta com suporte amigável a Java.
Para utilizar o SDK deve-se seguir o passo-a-passo abaixo.
- Ter um usuário cadastrado no Zenvia NLU;
- Acessar a página Zenvia NLU e fazer o login;
- Na sidebar ir até o ícone Connect e selecionar Canais;
- Na tela de canais, escolher a opção APP você será redirecionado para página de Integração com APP;
-
Em Integrações com APP, clicar no botão + no canto direito inferior, que abrirá o formulário Nova integração para preenchimento dos campos obrigatórios com Nome da integração, opções de seleção de Assistente e Squads, e clicar no botão adicionar após o preenchimento dos campos;
-
De volta na tela de Integrações com APP, deverá aparecer a integração configurada e ao clicar no botão de edição, será redirecionado para página de Editar integração onde deve conter os dados configurados no passo anterior, além dos campos contendo o Segredo de autorização, Chave de criptografia (ambos contendo os botões de Exibir e Esconder), Tempo de inatividade (tendo por padrão 1h, e podendo ser configurado em um mínimo de 10 minutos e no máximo 24h), chekbox para Notificação de push e abaixo aparecerão as informações de Autenticação para verificação;
-
Ao fazer qualquer alteração, clique no botão Salvar no topo da tela.
Tendo um dispositivo Android para testar
-
Após baixar o APP, deve-se acessar a tela de Editar integração do Zenvia NLU para copiar as informações de autenticação;
-
Ao abrir o App, deve-se preencher os campos:
- SourceId;
- Slug;
- Secret;
- Channel (repetir o SourceId);
- Salvar histórico de conversa (selecionar Always ou Ongoing);
- Ambiente do websocket (selecionar Dev, Staging, Prod ou Custom);
- Ambiente do chat (selecionar Dev, Staging, Prod ou Custom);
- Após preencher toda a configuração, deve-se clicar no botão de chat no canto diteito inferior da tela e será direcionado para o chatbot.
- Esse App foi desenvolvido para troca de mensagens do tipo texto entre o usuário e o bot, os demais componentes suportados pelo Zenvia NLU serão desenvolvidos futuramente.
Para usar o SDK deve-se importar no gradle do aplicativo:
implementation 'cx.d1:altusdk:${Version}'
Pode-se usar manualmente também, exemplo: https://www.androidbugfix.com/2021/12/how-to-import-aar-module-on-android.html
- Baixar o diretório aar.
- Adicionando ao seu projeto.
- Configurando gradle para usar o aar.
O ponto mais adequado e recomendado para configurar o SDK é na classe Application do seu aplicativo.
Caso ainda não tenha definido uma classe Application dedicada, pode-se iniciar o SDK na Activity principal, mas é altamente recomendável usar no Application.
Adicione no método onCreate do Application o código:
Kotlin
D1AltuSdk.init(this)
val config = D1AltuSdkConfig
.setSlug("valor ha informar pela d1")
.setSecret("valor ha informar pela d1")
.setConversationHistoryType(ConversationHistoryType.ALWAYS)
.setWebSocketEnvironment(D1AltuSdkWebSocketEnvironment.DEV)
.setEnvironment(D1AltuSdkEnvironment.DEV)
D1AltuSdk.setup(config)
Java
D1AltuSdk.INSTANCE.init(this);
D1AltuSdkConfig config = D1AltuSdkConfig.INSTANCE
.setSlug("valor ha informar pela d1")
.setSecret("valor ha informar pela d1")
.setConversationHistoryType(ConversationHistoryType.ALWAYS)
.setWebSocketEnvironment(D1AltuSdkWebSocketEnvironment.DEV)
.setEnvironment(D1AltuSdkEnvironment.DEV);
D1AltuSdk.INSTANCE.setup(config);
Para abrir conexão com o chat e apresentar a tela para o cliente
D1AltuSdk.openChat(
widgetIdentifier: String,
sourceId: String,
data: HashMap<String, String>? = null,
extraHash: String? = null
)
Segue um detalhamento dos objetos e métodos do SDK
D1AltuSdkConfig
- Objeto responsável por definir as configurações usadas no SDK. Só pode haver uma configuração ativa por vez.
O D1AltuSdkConfig implementa o padrão builder para criar objetos de configuração.
val config = D1AltuSdkConfig
.setSlug("valor ha informar pela d1")
.setSecret("valor ha informar pela d1")
.setConversationHistoryType(ConversationHistoryType.ALWAYS)
.setAssistantEnvironment(D1AltuAssistantEnvironment.HOMOL)
.setWebSocketEnvironment(D1AltuSdkWebSocketEnvironment.DEV)
.setEnvironment(D1AltuSdkEnvironment.DEV)
Configura a identificação do cliente.
Parâmetros:
- slug: String - Obrigatório
Exemplo:
D1AltuSdkConfig.setSlug("zenvia")
Configura a chave de acesso fornecida pelo canal App.
Parâmetros:
- secret: String - Obrigatório
Exemplo:
D1AltuSdkConfig.setSecret("a1b2c3d4e5f6g7")
Define o comportamento para histórico de conversas, podendo ser configurado como ALWAYS ou ONGOING.
- ALWAYS: Irá armazenar o histórico de mensagens enviadas no atendimento que foi iniciado com essa opção configurada no tipo de histórico.
- ONGOING: Não irá armazenar o histórico de mensagens enviadas no atendimento que foi iniciado com essa opção configurada no tipo de histórico. Quando iniciado um novo atendimento, a tela de chat não terá mensagens anteriores (a menos que algum atendimento anterior tenha sido iniciado com a configuração ALWAYS).
Parâmetros:
- type: ConversationHistoryType - Obrigatório
Exemplo:
D1AltuSdkConfig.setConversationHistoryType(ConversationHistoryType.ALWAYS)
// ou
D1AltuSdkConfig.setConversationHistoryType(ConversationHistoryType.ONGOING)
Define qual ambiente do assistente que será utilizado, podendo ser escolhido entre a versão de desenvolvimento, homologação e publicada.
Parâmetros:
- environment: D1AltuAssistantEnvironment - Obrigatório
Exemplo:
D1AltuSdkConfig.setAssistantEnvironment(D1AltuAssistantEnvironment.DEV)
// ou
D1AltuSdkConfig.setAssistantEnvironment(D1AltuAssistantEnvironment.HOMOL)
// ou
D1AltuSdkConfig.setAssistantEnvironment(D1AltuAssistantEnvironment.PUBLISHED)
Define o ambiente que será usado do WebSocket.
Parâmetros:
- webSocketEnvironment: D1AltuSdkWebSocketEnvironment - Obrigatório
Exemplo:
D1AltuSdkConfig.setWebSocketEnvironment(D1AltuSdkWebSocketEnvironment.DEV)
Define o ambiente que será usado.
Parâmetros:
- environment: D1AltuSdkEnvironment - Obrigatório
Exemplo:
D1AltuSdkConfig.setEnvironment(D1AltuSdkEnvironment.DEV)
Inicializador do SDK, deve ser configurado na classe Application do aplicativo:
fun init(applicationContext: Context)
Configurador do SDK, utilizado como exemplo para definir os ambientes de desenvolvimento:
fun setup(config: D1AltuSdkConfig)
Observer de interação de notificação da plataforma ALTU:
D1AltuSdk.setChatNotificationListener(object : ChatNotificationListener {
override fun onChatNotificationReceived(): Boolean {
return if (D1AltuSdk.hasNotificationData()) {
D1AltuSdk.consumeNotificationData()?.let(::openChat) ?: false
} else {
false
}
}
})
- true -> Informa para o SDK não seguir com o tratamento default. O tratamento fica a cargo do desenvolvedor. Como por exemplo abrir uma determinada activity em específico.
- false -> O SDK segue com seu tratamento default como por exemplo abrindo a activity principal do aplicativo.
Utilizado para iniciar uma conversação via chat:
fun openChat(widgetIdentifier: String,sourceId: String,data: HashMap<String, String>? = null,extraHash: String? = null)
Retorna os dados da notificação de chat:
fun getNotificationData(): String
Indica se existe dados de notificação disponivel:
fun hasNotificationData(): Boolean
Retorna os dados de notificação e limpa os dados dessa notificação:
fun consumeNotificationData(): String?
<style name="altuStyle">
<item name="altu_main_color">@color/altu_main_color</item>
<item name="altu_secondary_color">@color/altu_secondary_color</item>
<item name="altu_main_text_color">@color/altu_main_text_color</item>
<item name="altu_secondary_text_color">@color/altu_secondary_text_color</item>
<item name="altu_background_color">@color/altu_background_color</item>
<item name="altu_avatar">@drawable/avatar_chat_boot</item>
<item name="altu_chat_avatar">@drawable/avatar_chat_boot</item>
<item name="altu_chat_title">@string/chat_title_name</item>
</style>
Para habilitar a integração com push notifications basta inicializa na classe Application do seu projeto o SDK de Push da seguinte forma:
D1PushSdk.setup(this, D1PushSdkConfig)
Caso haja a necessidade de alterar as cores da tela de chat, é possível definir alguns parâmetros de estilização para obter o resultado desejado.
Declare o estilo abaixo no arquivo styles.xml
:
<style name="altuStyle">
<item name="znlu_primary_color">@color/znlu_primary_color</item>
<item name="znlu_on_primary_color">@color/znlu_on_primary_color</item>
<item name="znlu_secondary_color">@color/znlu_secondary_color</item>
<item name="znlu_on_secondary_color">@color/znlu_on_secondary_color</item>
<item name="znlu_background">@color/znlu_background</item>
<item name="znlu_medium">@color/znlu_medium</item>
<item name="znlu_dark">@color/znlu_dark</item>
</style>
TBD