Documentação para desenvolvedores do JSSDK do plugin de chat SaleSmartly

1. Introdução

Após inserir o código (ssq é uma variável global), você pode fazer alterações nas mensagens e chamadas da janela de bate-papo pelos seguintes métodos.

2. API

Retorno de chamada do status do comando

As seguintes 8 APIs públicas suportam um retorno de chamada opcional para o status do comando: setLoginInfo, clearUser, chatOpen, chatClose, sendTextMessage, setInputText, hideUpload e hideCloseIcon.

• Para comandos com carga útil, use ssq.push(command, payload, callback).
• Para comandos sem carga útil, use ssq.push(command, callback).
• O retorno de chamada é opcional. Chamadas existentes sem um retorno de chamada continuam funcionando.
• Nesta versão, o retorno de chamada recebe apenas { status } e é chamado no máximo uma vez por comando.

2.2.1 Configurar informações de login

Você pode configurar as informações do usuário após o login e, consequentemente, visualizar as informações configuradas no sistema de atendimento ao cliente.

 ssq.push('setLoginInfo', {
  user_id: 'b58e64cfxs2ym', // Encrypted User ID (Required). Maximum length: 300 characters.
  user_name: 'test_yy', // Required, Username
  language: 'ru-RU', // Plugin Language
  phone: '861592014xxxx', // The mobile phone number must be filled in the complete format including the country code; mobile phone numbers without area codes may result in errors in identifying the country or region or be identified as invalid numbers.
  email: 'test@test', // Email
  description: 'comboB\nClient\nFee-charging customers', // Description
  label_names: ['Label1','Label2'], // The name of the tag value. This is an overwrite method. Only tag values ​​created by the system can be passed.
  update_label_type: 'update', // Method of passing labels append - append labels update - overwrite previous labels
  custom_fields_ext: {"1210":"test11","more":["s1","s2"]}, // Custom fields, find the id and corresponding value in the custom fields of the project settings and fill them in (select the type to be passed in as an array), which can be viewed in the customer information
}, function(result) {
  console.log('setLoginInfo status:', result.status);
});

Status do retorno de chamada:

• success: As informações de login foram aplicadas.
• failed: Não foi possível concluir o login.
• ignored: O comando foi substituído por um comando de identidade mais recente.

Compartilhe as informações de login por meio de um link exclusivo.

Um link exclusivo pode passar informações do usuário para o comando existente setLoginInfo. Os campos suportados são os mesmos do exemplo acima. Antes de carregar o install.js raiz, a página enfileira as informações do usuário em ssq. Nenhuma API de backend adicional é necessária.

Método 1: Transmitir informações através da URL

Use este método quando o link exclusivo for aberto diretamente em um navegador ou copiado e compartilhado. O valor de setLoginInfo deve ser um objeto JSON codificado em URL.

 const loginInfo = {
  user_id: 'b58e64cfxs2ym', // Encrypted User ID (Required). Maximum length: 300 characters.
  user_name: 'test_yy', // Required, Username
  language: 'ru-RU', // Plugin Language
  phone: '861592014xxxx', // The mobile phone number must be filled in the complete format including the country code; mobile phone numbers without area codes may result in errors in identifying the country or region or be identified as invalid numbers.
  email: 'test@test', // Email
  description: 'comboB\nClient\nFee-charging customers', // Description
  label_names: ['Label1','Label2'], // The name of the tag value. This is an overwrite method. Only tag values ​​created by the system can be passed.
  update_label_type: 'update', // Method of passing labels append - append labels update - overwrite previous labels
  custom_fields_ext: {"1210":"test11","more":["s1","s2"]}, // Custom fields, find the id and corresponding value in the custom fields of the project settings and fill them in (select the type to be passed in as an array), which can be viewed in the customer information
};

const serviceLink =
  'https://chat.example.com/service/example-id?setLoginInfo='
  + encodeURIComponent(JSON.stringify(loginInfo));

Formato final do link:

 https://chat.example.com/service/example-id?setLoginInfo=<URL-encoded JSON>

Este método pode expor o nome, número de telefone, endereço de e-mail e outras informações do usuário na URL, no histórico do navegador ou em registros de acesso relacionados. Use-o de acordo com suas necessidades de privacidade.

Método 2: Passar informações através do postMessage em um WebView do aplicativo

Para um WebView de aplicativo, use um link exclusivo que não contenha informações do usuário:

 https://chat.example.com/service/example-id?loginSource=postMessage

Após a página WebView terminar de carregar, use a funcionalidade de execução de JavaScript da WebView para executar o seguinte código na página atual:

 window.postMessage(
  JSON.stringify({
    type: 'service-link-login',
    version: 1,
    payload: {
      user_id: 'b58e64cfxs2ym', // Encrypted User ID (Required). Maximum length: 300 characters.
      user_name: 'test_yy', // Required, Username
      language: 'ru-RU', // Plugin Language
      phone: '861592014xxxx', // The mobile phone number must be filled in the complete format including the country code; mobile phone numbers without area codes may result in errors in identifying the country or region or be identified as invalid numbers.
      email: 'test@test', // Email
      description: 'comboB\nClient\nFee-charging customers', // Description
      label_names: ['Label1','Label2'], // The name of the tag value. This is an overwrite method. Only tag values ​​created by the system can be passed.
      update_label_type: 'update', // Method of passing labels append - append labels update - overwrite previous labels
      custom_fields_ext: {"1210":"test11","more":["s1","s2"]}, // Custom fields, find the id and corresponding value in the custom fields of the project settings and fill them in (select the type to be passed in as an array), which can be viewed in the customer information
    },
  }),
  window.location.origin,
);

loginSource=postMessage indica explicitamente à página que o aplicativo fornecerá informações do usuário após o carregamento da página. A página não carrega o SDK até receber uma mensagem válida, impedindo a criação de um usuário anônimo antes da transição para um usuário identificado.

• Se nem setLoginInfo nem loginSource=postMessage forem fornecidos, o comportamento atual permanece inalterado. O SDK é carregado imediatamente e executado como um visitante anônimo.
• Se a URL contiver dados válidos setLoginInfo, os dados da URL terão prioridade e a página não aguardará uma mensagem do aplicativo.
• Os dados da mensagem devem ser uma string JSON. type deve ser service-link-login, version deve ser 1 e payload deve ser um objeto que não seja uma matriz.
• A página aceita apenas mensagens enviadas pela janela atual com a origem da página atual. Outros comandos do SDK e a troca de identidade em tempo de execução não são suportados.
• Se nenhuma mensagem válida for recebida em 3 segundos, a página não carregará o SDK e exibirá o aviso de link inválido. O aplicativo deverá enviar a mensagem novamente após uma atualização, reentrada na página ou recriação da WebView.
• O aplicativo não precisa aguardar um evento de prontidão, ACK ou resultado de criação de usuário do SDK.
• postMessage apenas impede que as informações do usuário apareçam na URL; não autentica a identidade. O aplicativo deve restringir a WebView à página HTTPS esperada.

2.2.2 Limpar informações de login do usuário

Você pode limpar manualmente as informações de login do usuário para uso em sites PWA, o que é executado após o logout e sem atualizar a página.

 ssq.push('clearUser', function(result) {
  console.log('clearUser status:', result.status);
});

Status do retorno de chamada:

• success: A identidade do usuário local foi apagada. A limpeza de uma identidade já vazia também foi bem-sucedida.

2.2.3 Abra a janela de bate-papo

A janela de chat pode ser aberta manualmente pelo programa em alguns cenários específicos, nos quais os usuários podem ser orientados a consultar o serviço de atendimento ao cliente, como em casos de falha no pagamento.

 ssq.push('chatOpen', function(result) {
  console.log('chatOpen status:', result.status);
});

Status do retorno de chamada:

• success: A janela de bate-papo foi aberta.
• failed: Não foi possível abrir a janela de bate-papo.
• ignored: A janela já estava aberta, a abertura foi bloqueada ou a ação foi interrompida por chatClose.

2.2.4 Feche a janela de bate-papo

Você pode fechar a janela de bate-papo manualmente com o programa.

 ssq.push('chatClose', function(result) {
  console.log('chatClose status:', result.status);
});

Status do retorno de chamada:

• success: A janela de bate-papo foi fechada.
• ignored: A janela já estava fechada ou a ação foi interrompida por chatOpen.

2.2.5 Monitorar mensagens não lidas

Monitore mensagens não lidas para notificações de mensagens personalizadas.

 ssq.push('onUnRead', function(obj) {
    console.log(obj.num); // Unread count
    console.log(obj.list); // Unread content
});

2.2.6 Ocultar ícones

Ícones personalizados podem ser implementados combinando "monitorar mensagens não lidas" e "abrir janela de bate-papo".

 window.__ssc.setting = { hideIcon: true}; 

2.2.7 Monitorar mensagens enviadas por visitantes

Monitore as mensagens dos visitantes e, em seguida, realize análises estatísticas ou relatórios de dados, que podem ser usados para estatísticas de eficácia da publicidade ou atribuição.

 ssq.push('onSendMessage', function(obj) {
    console.log(obj);
});

2.2.8 Ouvir as mensagens recebidas pelos visitantes

Monitore as informações recebidas pelos visitantes e, em seguida, realize análises estatísticas ou relatórios de dados, que podem ser usados para estatísticas de eficácia da publicidade ou atribuição.

 ssq.push('onReceiveMessage', function(obj) {
    console.log(obj);
});

2.2.9 Janela do monitor aberta

Monitore a janela aberta e, em seguida, realize estatísticas ou relatórios de dados, que podem ser usados para estatísticas de eficácia de publicidade ou atribuição.

 ssq.push('onOpenChat', function() {
    // Reporting data
});

2.2.10 Janela do monitor fechada

Monitore a janela fechada e você poderá gerar relatórios de dados para análise.

 ssq.push('onCloseChat', function() {
    // Execute other events
});

2.2.11 Ouvir a coleta aberta de informações

Ouça as informações coletadas (pesquisa pré-chat e retenção de informações offline) e relate os dados na ligação de retorno.

 ssq.push('onOpenCollection', (obj) => {
  // obj.type = 'offline' offline information
  // obj.type = 'survey'  pre-chat survey
});

2.2.12 O monitoramento completa a coleta de informações.

Após a conclusão do monitoramento e coleta de informações (investigação prévia ao chat e retenção de informações offline), os dados podem ser relatados para análise.

 ssq.push('onCollectionInfo', (obj) => {
  // obj contains the data provided by the user during the information collection process
});

2.2.13 Ouvir eventos de clique em ícones

Execute ações correspondentes monitorando os eventos de clique em diferentes ícones de plug-ins. Essa abordagem pode ajudar a rastrear o comportamento de interação do usuário.

 // Listening for clicks Line
ssq.push('onOpenLine', (obj) => {
  
  console.log('Line icon clicked', obj);
});

// Listening for clicks Messenger
ssq.push('onOpenMessenger', (obj) => {
  
  console.log('Messenger icon clicked', obj);
});

// Listening for clicks Email
ssq.push('onOpenEmail', (obj) => {
  
  console.log('Email icon clicked', obj);
});

// Listening for clicks Telegram
ssq.push('onOpenTelegram', (obj) => {
  
  console.log('Telegram icon clicked', obj);
});

// Listening for clicks Whatsapp
ssq.push('onOpenWhatsapp', (obj) => {
  
  console.log('Whatsapp icon clicked', obj);
});

// Listening for clicks WeChat
ssq.push('onOpenWeixin', (obj) => {
  
  console.log('WeChat icon clicked', obj);
}); 

// Listening for clicks VKontakte
ssq.push('onOpenVKontakte',  (obj) => { 
  
  console.log('VKontakteicon clicked', obj); 
}); 

// Listening for clicks TikTok
ssq.push('onOpenTikTok', (obj) => {
  
  console.log('TikTok clicked', obj); 
}); 

// Listening for clicks Custom
ssq.push('onOpenCustom', (obj) => { 
 // obj = {
 //     id, // custom_1、custom_2、custom_3
 //     content,
 // }
    console.log('Custom clicked', obj); 
}); 

// Listening for clicks Zalo
ssq.push('onOpenZalo', (obj) => {

  console.log('Zalo icon clicked', obj);
});

// Listening for clicks LineApp
ssq.push('onOpenLineApp', (obj) => {

  console.log('LineApp icon clicked', obj);
});

2.2.14 Monitorar a conclusão do carregamento de recursos do plugin

O plugin monitora o processo de carregamento de recursos até sua conclusão e executa eventos específicos após esse carregamento ser finalizado.

 ssq.push('onReady', () => {
  // Execute other events
});

// Usage Examples：
<script id="ss_chat" defer src="https://example.js"></script>

<script>
   const ss_chat = document.getElementById('ss_chat');
   ss_chat.addEventListener('load', (e) => {
      window.ssq && window.ssq.push('onReady', () => {
        // Execute other events
      });
   })
</script>

2.2.15 Personalizar o texto de redirecionamento do WhatsApp

Permite definir uma saudação ou mensagem personalizada que será exibida quando o usuário clicar no ícone do WhatsApp para acessar o site oficial do WhatsApp.

 ssq.push('createWhatsappGreeting', function(msg){
    // msg defaults to Hello.
    return msg + 'tony'; // Output：Hello.tony
    // If you need full customization, you can directly return the customized text

});

2.2.16 Enviar mensagens de texto no cliente

Implemente uma funcionalidade que permita aos visitantes iniciar proativamente a busca por informações.

 ssq.push('sendTextMessage', 'it is an error', function(result) {
  console.log('sendTextMessage status:', result.status);
});

Status do retorno de chamada:

• success: O servidor confirmou a mensagem em 20 segundos.
• failed: Nenhuma confirmação bem-sucedida foi recebida em 20 segundos.
• ignored: A mensagem não foi enviada ou o envio pendente foi cancelado.

2.2.17 Desativar função de upload

Pode ser usado para desativar a função de upload correspondente no lado do visitante.

 ssq.push('hideUpload', ['img', 'video', 'document'], function(result) {
  console.log('hideUpload status:', result.status);
});
// 'img' Image Type
// 'video' Video Type
// 'document' Document Type

// If the function is set to be closed and you want to reopen it in a certain operation, remove the corresponding item in the array and call it again.
// For example：ssq.push('hideUpload', [])

Status do retorno de chamada:

• success: As configurações de visibilidade de upload foram aplicadas.

2.2.18 Ocultar o botão de fechar janela

Oculte o botão de fechar janela no canto superior direito da janela de bate-papo.

 ssq.push('hideCloseIcon', function(result) {
  console.log('hideCloseIcon status:', result.status);
});

Status do retorno de chamada:

• success: O ícone de fechar estava oculto.

Utilizado para obter a altura real exibida da área de entrada do plugin de chat atual na página, em pixels.

A “área de entrada” inclui os elementos de entrada do plugin atualmente visíveis, como a barra lateral recolhida, a barra lateral expandida, a entrada com um único ícone e a lista de ícones de canais. O SDK calcula a altura vertical total ocupada por esses elementos de entrada visíveis e a retorna por meio de um callback.

Esta API é adequada para cenários em que a página principal precisa evitar sobreposição com a entrada do plugin de chat, como ajustar a posição de botões flutuantes personalizados, pop-ups de notificação personalizados, barras de ferramentas inferiores ou outros elementos de posição fixa.

 ssq.push('getSidebarHeight', function(height) {
    console.log(height); // Current height occupied by the plugin entry area, in px
});

Recomenda-se chamar esta API após o evento onReady para garantir que a configuração do plugin e os elementos de entrada tenham sido inicializados:

 ssq.push('onReady', function() {
    ssq.push('getSidebarHeight', function(height) {
        // For example: adjust the position of a floating element on the host page based on the plugin entry height
        console.log('Current sidebar height:', height);
    });
});

2.20 Preencha previamente a caixa de entrada

Use esta API para preencher previamente a caixa de entrada do widget de chat com o texto especificado. Os visitantes podem continuar editando o rascunho e enviá-lo manualmente. Chamar esta API não abre a janela de chat, não alterna a visualização atual, não focaliza a caixa de entrada nem envia uma mensagem.

text deve ser uma string. O widget armazena o resultado do JavaScript text.slice(0, 1000), limitando o rascunho às primeiras 1000 unidades de código UTF-16. Passe uma string vazia para limpar o rascunho atual. Se a API for chamada várias vezes, a última chamada executada determinará o rascunho atual.

 ssq.push('setInputText', 'Text to prefill', function(result) {
  console.log('setInputText status:', result.status);
});

// Clear the input draft
ssq.push('setInputText', '');

Status do retorno de chamada:

• success: A versão preliminar foi atualizada.