Etapas de integração do Freshchat Flutter SDK

ÍNDICE

• Pré-requisitos
• Obtenha seu APP ID, APP Key e Domain
  • 1. Adicione o Freshchat SDK ao seu projeto
    • 1.1. Configuração do iOS
    • 1.2. Configuração do Android
  • 2. Inicialização do SDK
  • 2.1 Opções de configuração para inicialização
  • 2.2 Localização de strings (iOS)
    • 2.2.1 Android
    • 2.2.2 iOS
  • 2.3 Opções de personalização da interface do usuário
    • 2.3.1 Android
    • 2.3.2 iOS
• 3. Informações do usuário
  • 3.1 Atualização das informações do usuário
  • 3.2 Atualizando Propriedades do Usuário (Metadados)
  • 3.3 Registrar eventos do usuário na linha do tempo
  • 3.4 Redefinir dados do usuário
  • 3.5 Restaurar usuário
  • 3.6 Obter ID de usuário do Freshchat
• 4. Iniciando a solução de suporte
  • 4.1 Conversas
  • 4.2. Perguntas frequentes
  • 4.2.1 Opções de perguntas frequentes
• 5. API de envio de mensagem
• 6. Notificações push
  • 6.1.1 Integração do lado do servidor
  • 6.1.2 Integração do lado do cliente - Android
• 7. Mudança de localidade do aplicativo em tempo de execução (Android)
• 8. Interceptar e manipular links Non-Freshchat no aplicativo
• 9. Outras Notas
  • 9.1 Aplicativo de amostra
  • 9.2 Compatibilidade com iOS 10

Pré-requisitos

O Flutter v1.10.0 e superior serão compatíveis com o Freshchat SDK.

Obtenha seu APP ID, APP Key e Domain

Sua conta do Freshchat está associada a um ID de APP exclusivo e a uma chave de APP que é usada para integrar seu SDK móvel ao Freshchat.

Faça login na sua conta do Freshchat como proprietário/administrador da conta. 

Vá para Admin > Mobile SDK. Você pode encontrar seu APP ID, APP Key e Domain aqui. 

1. Adicione o Freshchat SDK ao seu projeto

1. O nome do plug-in do Freshchat é 'freshchat_sdk'.

2. No arquivo pubspec.yaml do seu projeto flutter, em dependências, adicione 

   freshchat_sdk: "{{latest-version}}"

   Genérico

Para a versão mais recente do SDK, consulte o seguinte link: 

https://pub.dev/packages/freshchat_sdk

1.1. Configuração do iOS

Execute o comando abaixo para vincular automaticamente o SDK 

cd ios pod install

1.2. Configuração do Android

Quando o aplicativo é direcionado ao Android 7.0+ e o anexo de imagem está ativado, o FileProvider precisa ser configurado.

Inclua o provedor no AndroidManifest.xml conforme abaixo.

AndroidManifest.xml

<provider   android:name="androidx.core.content.FileProvider"    android:authorities="com.example.demoapp.provider"    android:exported="false"    android:grantUriPermissions="true">    <meta-data        android:name="android.support.FILE_PROVIDER_PATHS"        android:resource="@xml/freshchat_file_provider_paths" />
</provider>

Strings.xml

<string name="freshchat_file_provider_authority">com.example.demoapp.provider
</string>

2. Inicialização do SDK

Invoque Freshchat.init() com seu ID de aplicativo, chave de aplicativo e domínio antes de invocar/tentar usar qualquer outro recurso do Freshchat SDK.  

É altamente recomendável invocar init() na inicialização da tela de inicialização/suporte do aplicativo. O Freshchat SDK verifica a presença de seus componentes durante init() e avisará sobre componentes ausentes quando detectar que os componentes estão ausentes ou suas entradas de manifesto estão ausentes. 

Substitua YOUR-APP-ID, YOUR-APP-KEY e YOUR-DOMAIN no snippet de código a seguir pelo ID e chave do aplicativo reais.

Freshchat.init(YOUR-APP-ID, YOUR-APP-KEY,YOUR-DOMAIN);

2.1 Opções de configuração para inicialização

Ative ou desative recursos como captura de câmera adicionando os parâmetros opcionais para a configuração específica

Freshchat.init(YOUR-APP-ID, YOUR-APP-KEY,YOUR-DOMAIN,          teamMemberInfoVisible:true,          cameraCaptureEnabled:true,          gallerySelectionEnabled:true,          responseExpectationEnabled:true,          showNotificationBanner:true,                                       notificationSoundEnabled: true);

Freshchat.init(YOUR-APP-ID, YOUR-APP-KEY,YOUR-DOMAIN,stringsBundle: “bundleName”);

Freshchat.init(YOUR-APP-ID, YOUR-APP-KEY,YOUR-DOMAIN,themeName: “themeFile.plist”);

3. Informações do usuário

3.1 Atualização das informações do usuário

Você pode enviar informações básicas do usuário a qualquer momento para fornecer mais contexto sobre o usuário quando seus agentes de suporte estiverem trocando mensagens com eles. 

import 'package:freshchat_sdk/freshchat_user.dart';
FreshchatUser freshchatUser;
freshchatUser.setFirstName("John");
freshchatUser.setLastName("Doe");
freshchatUser.setEmail("johndoe@dead.man");
freshchatUser.setPhone("+91","1234234123");
Freshchat.setUser(freshchatUser);

3.2 Atualizando Propriedades do Usuário (Metadados)

Você pode capturar e enviar metadados adicionais sobre o usuário e os eventos no aplicativo, o que também se torna uma forma de segmentar seus usuários para posteriormente enviar mensagens para eles. 

var userPropertiesJson = 
{   "user_type": "Paid",   "plan": "Gold"
}
Freshchat.setUserProperties(userPropertiesJson);

3.3 Registrar eventos do usuário na linha do tempo

O rastreamento de eventos do usuário fornece mais informações e contexto sobre o(s) usuário(s) em seu aplicativo. Eventos como ações do usuário, casos de falha/erro podem ser rastreados usando esta API. Os eventos rastreados são listados na Linha do tempo de eventos no lado do agente.

var eventName = "Visited Order Details page";
var eventProperties = {"Order Id": 3223232332,                       "Order Date": "24 Jan 2020",                       "Order Status ": "In-Transit"};
Freshchat.trackEvent(eventName,                    properties: eventProperties);

3.4 Redefinir dados do usuário

Redefina os dados do usuário ao sair ou quando for considerado apropriado com base na ação do usuário no aplicativo invocando a API resetUser. 

Freshchat.resetUser();

3.5 Restaurar usuário

Para reter as mensagens de bate-papo em dispositivos/sessões/plataformas, o aplicativo móvel precisa passar o mesmo id externo e restaurar a combinação de id para o usuário. Isso permitirá que os usuários captem a conversa de qualquer uma das plataformas suportadas - Android, iOS e Web.

• Id externo - deve (idealmente) ser um identificador exclusivo para o usuário do seu sistema, como um id de usuário ou id de e-mail, etc. e é definido usando a API Freshchat.identifyUser(). Isso não pode ser alterado depois de definido para o usuário

• Id de restauração - Isso é gerado pelo Freshchat para o usuário atual, dado que um id externo foi definido e pode ser recuperado a qualquer momento usando a API user = Freshchat.getUser() e user.getRestoreId(). O aplicativo é responsável por armazenar e, posteriormente, apresentar a combinação de id externo e ID de restauração ao SDK do Freshchat para continuar as conversas de bate-papo em sessões no mesmo dispositivo ou em dispositivos e plataformas.

Observação: a ID de restauração para um usuário geralmente é gerada apenas quando o usuário envia uma mensagem.

As notificações são suportadas em apenas um dispositivo móvel a qualquer momento e é atualmente o último dispositivo restaurado ou dispositivo com o último token push atualizado

Para definir o ID externo 

Freshchat.identifyUser(externalId:"EXTERNAL_ID");

Para recuperar o id de restauração

FreshchatUser user = Freshchat.getUser();
var restoreId = user.getRestoreId();

Para pesquisar e restaurar o usuário por id externo e restaurar o id

Freshchat.identifyUser(externalId:"EXTERNAL_ID",restoreId:"RESTORE_ID");

A geração de ID de restauração é um processo assíncrono. Portanto, você precisa abrir um fluxo para onRestoreIdGenerated para ser notificado quando o ID de restauração for gerado. Este stream pode ser ouvido ao ouvir e não registrado ao cancelar seu stream de restauração e assinatura de stream do ouvinte, respectivamente.

Registre-se para o evento gerado pelo id de restauração

var restoreStream = Freshchat.onRestoreIdGenerated;
var restoreStreamSubscription = restoreStream.listen((event)
{    FreshchatUser user = Freshchat.getUser();    var restoreId = user.getRestoreId();    var externalId = user.getExternalId();
});

3.6 Obter ID de usuário do Freshchat

Você pode obter o identificador exclusivo de seu usuário usando a API getUserAlias.

var userAlias  = await Freshchat.getFreshchatUserId();

Use os snippets abaixo para iniciar a experiência de suporte baseada em perguntas frequentes ou conversas a partir de uma frase de chamariz em seu aplicativo. Sua chamada para ação ou ponto de entrada pode ser um botão na tela ou um item de menu.

4.1 Conversas

Em resposta a eventos de interface do usuário específicos, como uma seleção de menu ou botão no evento de clique, invoque a API showConversations() para iniciar o fluxo de conversa. Se o aplicativo tiver vários tópicos configurados, o usuário verá a lista de tópicos . A lista de Tópicos é ordenada conforme especificado no Painel (link para a lista de Tópicos no painel) quando não há mensagens. Quando há mensagens, a ordem é baseada no usado mais recentemente primeiro.

Observação: somente tópicos com visibilidade definida como "Visível para todos os usuários" serão exibidos ao usar a API showConversations()

Freshchat.showConversations();

4.1.1 Filtrando Tópicos

Para filtrar e exibir apenas tópicos marcados com um termo específico, use os parâmetros opcionais na API showConversations

Por exemplo: Para vincular e exibir apenas tópicos específicos da página de pedidos em seu aplicativo, esses tópicos específicos podem ser marcados com o termo "order_queries".

Freshchat.showConversations(filteredViewTitle:"Premium Support",tags:["premium"]);

Nota: Se nenhum Tópico correspondente for encontrado, o usuário será redirecionado para Tópicos.

Os tópicos que normalmente não são visíveis ao usar a API showConversations() também serão exibidos quando marcados e a tag específica for passada para a API filterByTags da instância ConversationOptions passada para a API showConversations().

4.1.2 Contagem não lida

Se você deseja obter o número de mensagens não lidas para o usuário na inicialização do aplicativo ou em qualquer outro evento específico, use a API getUnreadCountAsync e exiba a contagem.

void getUnreadCount async
{    var unreadCount = await Freshchat.getUnreadCountAsync
}

var unreadCountStream = Freshchat.onMessageCountUpdate;
unreadCountSubscription = unreadCountStream.listen((event)
{  print("New message generated: " + event.toString());
});

List<String> tags = ["sampleTag1","sampleTag2"];
void getUnreadCount async
{    var unreadCount = await Freshchat.getUnreadCountAsyncForTags(tags);
}

4.2. Perguntas frequentes

Em resposta a eventos específicos da interface do usuário, como uma seleção de menu ou botão no evento de clique, invoque a API showFAQs() para iniciar a tela de perguntas frequentes. Por padrão, as categorias de perguntas frequentes são exibidas como uma grade com um botão "Fale conosco" na parte inferior. Para personalizar isso, verifique as opções de perguntas frequentes.

Freshchat.showFAQ();

4.2.1 Opções de perguntas frequentes

As personalizações para o fluxo de perguntas frequentes podem ser obtidas especificando as opções relevantes nos parâmetros opcionais para personalização passados para a API showFAQs().

Freshchat.showFAQ(faqTitle:"Tags", faqTags:["premium"],faqFilterType: FaqFilterType.Article );

faqTitle - título dado à página da lista de resultados do filtro aplicado. 

faqTags - nome das tags com base em qual filtro é aplicado. 

faqFilterType - Categoria/Artigo. Categoria - combinação de artigos e subcategorias. Artigo - contém apenas artigos.

Nota: Quando não houver correspondência no filtro aplicado, ele exibirá todas as categorias do FAQ por padrão

4.2.2 Filtrando categorias de FAQ por tags

Para filtrar e exibir apenas categorias de perguntas frequentes marcadas com um termo específico, use o parâmetro faqFilterType com valor como enum FaqFilterType.Category passado para a API showFAQs() conforme abaixo.

Por exemplo: Para exibir categorias de FAQ relacionadas a um tipo de usuário específico, essas categorias de FAQ específicas podem ser marcadas com o termo "premium".

Freshchat.showFAQs(faqTags:["premium"],faqFilterType: FaqFilterType.Category );

4.2.3 Filtrando artigos de FAQ por tags

Para filtrar e exibir apenas as perguntas frequentes marcadas com um termo específico, use o parâmetro faqFilterType com valor como enum FaqFilterType.Article passado para a API showFAQs() conforme abaixo.

Observação: as perguntas frequentes também herdam as tags da categoria principal de perguntas frequentes.

Por exemplo: Para vincular as perguntas frequentes relacionadas à falha de pagamento, essas perguntas específicas podem ser marcadas com o termo "payment_failure" e podem ser vinculadas a partir da página de pagamentos no aplicativo.

Freshchat.showFAQs(faqTags:["payment_failure"],faqFilterType: FaqFilterType.Article);

4.2.4 Filtrar Tópicos exibidos ao clicar em "Fale Conosco" nas FAQs por tags

Para filtrar e exibir apenas Tópicos marcados com um termo específico quando o usuário clicar em "Fale Conosco" nas telas de FAQ, use o parâmetro contactUsTags com valor como Lista de tags passadas para showFAQs() API conforme abaixo.

Observação: o comportamento padrão para "Fale conosco" no fluxo de perguntas frequentes é o mesmo que invocar showConversations(), ou seja, exibirá todos os tópicos marcados como "Visível para todos os usuários", exceto quando a filtragem de tópicos estiver habilitada passando tags para a API filterContactUsByTags .

Por exemplo: Para exibir tópicos relacionados a uma seção específica do programa de perguntas frequentes, esses tópicos específicos podem ser marcados com o termo "payment_failure".

Freshchat.showFAQs(faqTitle:"Payments",                   faqTags:["payment_failure"],                   faqFilterType:FaqFilterType.Article,                   showFaqCategoriesAsGrid:true,                   showContactUsOnFaqScreens:true,                   showContactUsOnFaqNotHelpful:true,                   contactUsTags:["payments"]);

5. API de envio de mensagem

O aplicativo pode enviar uma mensagem em nome do usuário usando a API sendMessage(). 

Observação: esta API enviaria silenciosamente uma mensagem e não iniciaria a interface do usuário do Freshchat SDK

Por exemplo: Para enviar uma mensagem em um tópico marcado como "premium", a API pode ser invocada conforme abaixo.

String tag = "premium";
String message = "text message";
Freshchat.sendMessage(tag,message);

6. Notificações push

A integração da notificação por push do Freshchat em seu aplicativo ajudará os usuários a receber suas mensagens de suporte mais rapidamente.

6.1.1 Integração do lado do servidor

Android

No console do Firebase, em seu projeto, vá para a guia de mensagens na nuvem e você verá sua chave do servidor, copie-a. Se você não tiver uma conta do Firebase para seu aplicativo. Consulte  https://firebase.google.com/docs/android/setup

Salve esta chave do servidor FCM no portal da web Freshchat em Admin -> Mobile SDK

iOS

Consulte aqui para gerar o arquivo .p12 e carregá-lo no Freshchat

6.1.2 Integração do lado do cliente - Android

Siga as etapas abaixo para integrar notificações push em sua versão Android do aplicativo móvel. As etapas abaixo são sugeridas sob a suposição de que seu aplicativo está entregando outras notificações por push.

Passos

1. Salvando token push: Cada aplicativo terá um token push firebase. O Freshchat precisa desse token para enviar notificações push aos usuários. Você pode usar o snippet abaixo para enviar o token firebase para o Freshchat SDK.
   

   Freshchat.setPushRegistrationToken(token);

   Genérico

   
   
   

2. Passando a carga de notificação por push recebida para o SDK do Freshchat:

   FirebaseMessaging firebaseMessaging = FirebaseMessaging();
   firebaseMessaging.configure
   (    onMessage: (Map<String,dynamic> message)async
   {        if(await Freshchat.isFreshchatNotification(message['data']))
   {            Freshchat.handlePushNotification(message['data']);        }    }    onBackgroundMessage: myBackgroundMessageHandler);
   );

   Genérico
3. Para lidar com as notificações do Freshchat em segundo plano ou no estado eliminado :
   
   Siga esta documentação para configurar o suporte de notificação do FCM em segundo plano para seu aplicativo flutter. Registre o plug-in SDK do Freshchat dentro do método registerWith adicionando esta linha dentro dele.
   
   

   import com.freshchat.consumer.sdk.flutter.FreshchatSdkPlugin;
   public void registerWith(PluginRegistry registry)
   {
   FirebaseMessagingPlugin.registerWith(registry.registrarFor("io.flutter.plugins.firebasemessaging.FirebaseMessagingPlugin"));
        FreshchatSdkPlugin.register(registry)
   }

   HTML

   
   

4. Lide com a notificação em segundo plano do seu aplicativo flutter adicionando um método estático ou função de nível superior
   

   Future<dynamic> myBackgroundMessageHandler(Map<String,dynamic> message) async
   {        
   if(await Freshchat.isFreshchatNotification(message['data']))
   {              
   Freshchat.handlePushNotification(message['data']);    
   }}

   HTML

   
   

6.1.3 Integração do lado do cliente - iOS

Siga as etapas abaixo para integrar notificações push em sua versão iOS do aplicativo móvel. As etapas abaixo assumem que seu aplicativo está entregando outras notificações por push.

Objetivo C No arquivo AppDelegate.m, adicione as seguintes linhas de código 

#import "FreshchatSdkPlugin.h"

#import "FreshchatSdkPlugin.h"

O Freshchat SDK é capaz de receber notificações push para todas as conversas do usuário.

• Para ativá-lo, adicione a API setPushRegistrationToke ao método didRegisterForRemoteNotificationsWithDeviceToken delegado do seu aplicativo da seguinte maneira.

Objetivo C

[[[FreshchatSdkPlugin alloc]init] setPushRegistrationToken:devToken];

let freshchatSdkPlugin = FreshchatSdkPlugin()
freshchatSdkPlugin.setPushRegistrationToken(deviceToken)

Objetivo C

if([[[FreshchatSdkPlugin alloc]init] isFreshchatNotification:info]) 
{    [[FreshchatSdkPlugin alloc]init] handleRemoteNotification:info
andAppstate:app.applicationState];
}

let freshchatSdkPlugin = FreshchatSdkPlugin()
if freshchatSdkPlugin.isFreshchatNotification(userInfo)
{    freshchatSdkPlugin.handlePushNotification(userInfo)
}

Adicione o código abaixo em seu arquivo dart

Freshchat.setNotificationConfig(priority: Priority.PRIORITY_HIGH,                                importance: Importance.IMPORTANCE_DEFAULT,                                notificationSoundEnabled:true,                                largeIcon:"notif"// Drawable name,                                smallIcon:"notif"// Drawable name);

Identificamos algumas áreas potenciais onde o problema ocorre. Então, consolidamos isso em listas de verificação, verifique se você fez tudo.

iOS

1. Certifique-se de ter carregado o certificado push correto no portal Freshchat.

2. Certifique-se de que está verificando no ambiente de desenvolvimento ou produção e carregue o respectivo certificado no portal Freshchat.

3. Não faça check-in no simulador de iOS, pois ele não possui recurso de notificação por push. Execute testes e verifique usando um dispositivo iOS real.

4. O recurso de notificação por push deve estar ativado em seu projeto Xcode.

5. Certifique-se de conceder permissões para enviar notificações para seu aplicativo. Navegue até Admin  > seu aplicativo > habilite a notificação por push.

6.Confirme que você está passando o token do dispositivo para o Freshchat usando o seguinte método,

[[[FreshchatSdkPlugin alloc]init] setPushRegistrationToken:devToken];

8. Adicione os respectivos códigos de ponte flutuante nos métodos delegados de notificação por push.

9. Consulte os códigos aqui para a implementação do plug-in, confirme se você implementou todas as recomendações.

10. Se você tiver uma extensão de notificação em seu aplicativo, verifique se ela não está bloqueando a notificação.

Android

1. Certifique-se de ter adicionado a chave FCM correta do seu aplicativo no portal Freshchat

2. Não verifique os emuladores do Android, pois eles geralmente não têm o Google Play Service ativado. É melhor executar testes e verificar usando um dispositivo Android real.

3. Confirme se você está passando o token do dispositivo para o Freshchat usando o seguinte método,

Freshchat.setPushRegistrationToken(fcmToken);

4. Certifique-se de estar recebendo uma notificação do FCM.

5. Consulte os códigos aqui para implementação do plug-in, confirme se você implementou todas as recomendações

Se o problema persistir, tente o seguinte URL, https://<<your-freshchat-account-domain-here>>/app/api/notif_debug?convId= onde, CONV_ID é o ID da conversa para a qual você fez não receber notificação. CONV_ID é a última parte numérica da url quando você abre a conversa no navegador. Certifique-se de estar logado como Admin ao abrir este URL. Ele lhe dará o motivo por trás da falha na notificação por push.

7. Mudança de localidade do aplicativo em tempo de execução (Android)

Se seu aplicativo puder oferecer suporte a diferentes localidades (idiomas) além da localidade padrão do dispositivo, siga as etapas abaixo para atualizar a localidade em seu SDK do Freshchat.

1. Depois que o aplicativo mudar de localidade, notifique o SDK sobre a mudança de localidade do aplicativo usando o método abaixo,

Freshchat.notifyAppLocaleChange();

2. O Freshchat usa internamente o webview como parte do SDK, do sistema operacional Android versão 7.0, o webview muda de localidade durante o carregamento do webview. Para corrigir isso, fornecemos um stream para ouvir a mudança de localidade por webview

Ouça a transmissão onLocaleChangedByWebview

var webviewStream = Freshchat.onLocaleChangedByWebview;

webviewSubscription = webviewStream.listen((event)

{
 //change locale

});

var linkHandlerStream = Freshchat.onRegisterForOpeningLink;

linkHandlerStreamSubscrption = linkHandlerStream.listen((event)

{
       String url = event[“url”];

});

Recentemente, atualizamos nossa marca em nossas ofertas e alteramos os nomes de nossos planos de preços. Se você se inscreveu antes de 9 de agosto de 2021, clique em Planos anteriores para visualizar seus planos aplicáveis. 
Garantimos que essa alteração não afetará sua experiência com o produto e nenhuma ação é necessária de sua parte.