Flutter SDK

📘

A versão mais recente da SDK Flutter é a v3.6.8, que está disponível atualmente.

Passos da integração

1. Configuração do projeto no Firebase
2. Configuração no painel Inngage
3. Configuração nativa iOS
4. Configuração nativa Android

Instalação

Ambiente de desenvolvimento

Antes de começar a utilizar nossos SDKs, verifique se o seu ambiente de desenvolvimento possui o SDK do Dart e do Flutter instalados.

Importando o FCM Token (API Key)

Para aproveitar nossos SDKs, será necessário importar o FCM Token (API Key) do seu projeto Firebase em nossa plataforma. Siga o passo a passo neste link para executar essa ação.

Instalando o package utilizando o CLI do Flutter

Para adicionar o SDK Flutter da Inngage ao seu projeto, execute o seguinte comando utilizando o CLI do Flutter:

Shell

$ flutter pub add inngage_plugin

Este comando adiciona a seguinte linha no arquivo pubspec.yaml de seu pacote:

Dart

dependencies:
 inngage_plugin: ^3.6.8

Caso o pacote não tenha sido instalado corretamente, certifique-se que o inngage_plugin está em seu arquivo pubspec.yaml e rode o flutter pub get manualmente.

Inclusão da dependência

Após configurar o SDK Flutter da Inngage, é simples importá-lo em seu projeto. Para isso, basta adicionar o pacote ao seu código Dart:

Dart

import 'package:inngage_plugin/inngage_sdk.dart';

🚧

Recomendamos que você utilize a versão estável mais recente do Flutter, definida no arquivo pubspec.yaml. A Inngage SDK foi verificada pela última vez na versão Flutter 3.0.0 • canal estável.

Versões suportadas:

• SDK: >=2.18.0 <4.0.0
• Flutter: >=2.5.0"

---

Implementando a SDK

Notificações push

As notificações serão enviadas do servidor da Inngage para um ou mais dispositivos móveis, mesmo quando o aplicativo estiver em primeiro plano, segundo plano ou até mesmo fechado. Essas mensagens têm o objetivo de alertar o usuário sobre informações importantes, atualizações ou qualquer outro dado relevante relacionado ao seu aplicativo.

As notificações push aparecem na tela de bloqueio ou na barra de notificações do dispositivo. Quando o usuário toca na notificação, o aplicativo é aberto e pode direcioná-lo para uma página específica ou exibir mais detalhes sobre o conteúdo da notificação.

InngageSDK.subscribe()

Esse método deve ser chamado para informar o usuário sobre a chegada das notificações e inicializar o Inngage dentro do seu aplicativo. Geralmente, é chamado no arquivo main.dart, mas, dependendo da arquitetura do seu aplicativo, pode ser chamado dentro do MyApp(). Essa função é responsável por autorizar o acesso à API da Inngage e ao Firebase Cloud Messaging, além de ativar os listeners de notificações.

Dart

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await InngageSDK.subscribe(
    appToken: 'Trocar pelo App Token do aplicativo',
    friendlyIdentifier: 'Trocar pelo objeto Identificador do usuário',
    navigatorKey: navigatorKey,
    requestAdvertiserId: true,
    requestGeoLocator: true,
    blockDeepLink: true,
    firebaseListenCallback:(data) => print(data['additional_data']),
    phoneNumber: '5511999999999',
    email: '[email protected]',
  );
  runApp(MyApp());
}

O trecho de código menciona alguns parâmetros e funcionalidades do Inngage SDK no contexto do Flutter. Aqui está uma explicação das principais informações:

• appToken: É o token do aplicativo na plataforma Inngage, essencial para a comunicação com os serviços da Inngage.
• friendlyIdentifier: É usado para identificar o usuário dentro do sistema. Esse parâmetro deve ser preenchido para que o usuário possa ser corretamente associado e receber as notificações push de forma personalizada.
• navigatorKey: Uma Global Key no Flutter que pode ser usada para acessar o estado de um StatefulWidget. No caso do Inngage SDK, essa chave é usada para identificar a instância do Navigator dentro do aplicativo e é passada para o MaterialApp.
• requestAdvertiserId: Um valor booleano que, quando definido como true, solicita o Advertising Id do Android e o IDFA (Identifier for Advertisers) no iOS. O valor padrão é false.
• requestGeoLocator: Um valor booleano que, quando definido como true, solicita a permissão para acessar a localização do usuário antes de registrá-lo. O valor padrão é false.
• blockDeepLink: É um valor booleano que permite bloquear a ação do deep link de abrir um navegador. Ao definir como true, esse bloqueio é efetivado. O valor padrão é false.
• firebaseListenCallback: Permite que uma função seja passada para ser chamada no final do onBackgroundMessage do Firebase. Essa função será chamada quando o aplicativo estiver em segundo plano e receber uma notificação push. O parâmetro 'data' é um Map<String, dynamic> contendo informações da notificação push recebida do RemoteMessage message.data.
• phoneNumber: Você pode registrar o número de telefone/celular do usuário. O parâmetro é opcional.
• email: Você pode registrar o email do usuário. O parâmetro é opcional.

🚧

Os parâmetros "appToken", "friendlyIdentifier" e "navigatorKey" são requeridos ou obrigatórios.

No main.dart, a GlobalKey é passada como navigatorKey para o MaterialApp, que é a mesma navigatorKey usada no método InngageSDK.subscribe(). Essa associação é feita para permitir a correta integração entre o Inngage SDK e a navegação do aplicativo no Flutter.

Dart

@override
Widget build(BuildContext context) {
  return MaterialApp(
    navigatorKey: navigatorKey,
    home: HomePage(),
  );
}

InngageNotificationMessage.subscribe()

Esse método deve ser chamado para realizar as configurações de push no aplicativo e, principalmente, solicitar o acesso às notificações do usuário. Ao executar esse método, o aplicativo informa ao sistema operacional que deseja receber notificações push e é autorizado a fazê-lo, desde que o usuário conceda permissão para receber tais notificações.

Dart

void main() async {
  // Chamada do método "await InngageSDK.subscribe();"
  InngageNotificationMessage.subscribe(); // Configurações de push e solicitação de acesso às notificações

  runApp(MyApp());
}

Essa solicitação de acesso é fundamental para garantir que o aplicativo possa receber e exibir notificações push enviadas pela plataforma Inngage. É importante garantir que o método InngageNotificationMessage.subscribe() seja chamado corretamente no aplicativo para habilitar as notificações push e configurar adequadamente o sistema de notificação do usuário.

📘

Caso seja necessário registrar um usuário em uma área não logada do aplicativo, o parâmetro friendlyIdentifier deve ser fornecido como null. Nesse caso, o mesmo será atribuído com o valor do Device Token do usuário automaticamente.

Personalização (para sua identidade)

Adicionando Campos Personalizados

A SDK permite que o desenvolvedor que está integrando a SDK adicione campos customizáveis (customFields), como nome, e-mail, gênero, etc. No entanto, esses parâmetros devem ser configurados previamente na plataforma da Inngage.

Dart

final json = {
    "nome": "Leonardo",
    "dt_nascimento": "01/09/1970",
    "genero": "M"
  };

await InngageSDK.subscribe(
  // Outros parâmetros do método
  customFields: json,
);

Modificando o Identificador e adicionando novos Campos Personalizados

Ao preencher o parâmetro identifier no método addUserData, a API substitui o identifier fornecido na requisição e adiciona os demais campos personalizados (customFields). O mesmo appToken no subscribe() deve ser adicionado neste método.

Dart

InngageUtils.addUserData(
	appToken: 'Adicionar o App Token do aplicativo',
  identifier: 'Trocar pelo novo objeto Identificador do usuário',
  customFields: {
    "nome": "Leonardo",
    "dt_nascimento": "1970-09-10",
    "genero": "M"
  };
 );

O registration é preenchido automaticamente com o token FCM do aplicativo. Caso o campo identifier não for informado, a API realizará o registro dos campos personalizados sem alterar o respectivo valor.

Caso necessário, você também pode alterar o email e phoneNumber cadastrados no subscribe:

Dart

InngageUtils.addUserData(
	appToken: 'Adicionar o App Token do aplicativo', 
  email: "[email protected]", 
  phoneNumber: "11998981212"
)

Solicitação de permissão dos dados de localização

Ao integrar a SDK, você pode obter os dados de localização do usuário ao registrá-lo na Inngage.

Para isso, basta inserir como true o parâmetro requestGeoLocator disponível no InngageSDK.subscribe():

Dart

await InngageSDK.subscribe(
    requestGeoLocator: true,
  );

Enviando dados UTM para o Google Analytics

Agora, é possível enviar os parâmetros UTM configurados durante o envio de notificações push pela plataforma diretamente para o Google Analytics.

📘

Para aproveitar essa funcionalidade, certifique-se de que o plugin com.android.application no Gradle do seu projeto esteja atualizado para a versão 7.4.2 ou superior.

Alterando ícone de notificação em primeiro plano

Se o ícone da notificação push não estiver sendo atualizado conforme o configurado nos recursos (resources) do Android no seu projeto, você pode ajustá-lo utilizando o método InngageNotificationMessage.subscribe() da seguinte maneira:

Dart

await InngageNotificationMessage.subscribe(notificationIcon: "@mipmap/my_icon", backgroundIcon: Colors.red);

Certifique-se de adicionar o nome do arquivo do ícone localizado nas pastas: android > app > src > main > res .

Você também pode modificar a cor do icone de notificação pelo parâmetro backgroundIcon. O parâmetro aceita o tipo Color.

Envio de eventos

A SDK permite que o desenvolvedor que está integrando a SDK envie eventos customizados. É importante configurá-los na plataforma Inngage para garantir uma boa performance e integração.

Dart

await InngageEvent.sendEvent(
  eventName: 'compra',
  appToken: 'MyAppToken',
  identifier: '[email protected]',
  //registration: '', Firebase Token,
  conversion_event: true, //
  conversion_value: 1090.00, //Valor monetário da conversão
  conversion_notid: "2314klbkf41bsgav4hg12ab24v1h41", //ID da mensagem
  eventValues: {
  	'produto': 'Bola de tenis',//Exemplo
    'valor': '40'//Exemplo
  },
);

Existem três valores obrigatórios para garantir o correto funcionamento:

• eventName: Define o nome do evento, que será usado para identificá-lo rapidamente na plataforma.
• appToken: É necessário para validar suas credenciais.
• identifier: É usado para identificar o usuário dentro do sistema.

Você também pode adicionar valores avançados para esse evento usando o parâmetro eventValues, que é um array contendo chaves e valores com dados que serão anexados ao evento.

A API de eventos também pode receber um evento de conversão, para isso, existem os seguintes campos:

• conversion_event: Defina como True para indicar que é um evento de conversão.
• conversion_value: Esse campo permite inserir o valor monetário da conversão. O valor padrão é FLOAT 11000.00.
• conversion_notid: Opção para enviar o ID Único da Notificação da Inngage (NOTID), que foi recebido pelo app no momento do Push. Isso possibilita atribuir uma conversão a um determinado Push."

In App Messages

A SDK Flutter da Inngage possibilita a exibição de Mensagens In App para os usuários. Essas mensagens podem ser enviadas tanto pela plataforma quanto pela API e são automaticamente apresentadas com base nas configurações recebidas pelo payload do Firebase.

Para apresentar a mensagem In App, utilize o widget InngageInAppWidget nas páginas em que deseja habilitar essa funcionalidade:

Dart

@override
Widget build(BuildContext context) {
  return MaterialApp(
    navigatorKey: navigatorKey,
    home: InngageInAppWidget(child: HomePage()),
  );
}

É possível bloquear a abertura do deeplink e receber um callback com o link recebido na mensagem In App:

Dart

InngageInapp.blockDeepLink = true;
InngageInapp.deepLinkCallback = (link){
  print(link);
};

Essas configurações permitem uma maior personalização e controle sobre as Mensagens In App apresentadas ao usuário em seu aplicativo Flutter.

---

👍

Você está pronto para começar!

Seguindo os passos acima da documentação você estará pronto para utilizar todas as ferramentas necessárias para as funcionalidades da SDK. 👏

Possíveis incidentes

❗️

"Estou com problemas para abrir URLs no Android"

Se o seu aplicativo Android estiver enfrentando problemas para abrir URLs a partir da API 31 (Android 12), é necessário listar explicitamente os aplicativos com os quais deseja interagir no AndroidManifest.xml. Isso é necessário devido a mudanças relacionadas à privacidade na API 31.

Para solucionar esse problema, adicione a seguinte configuração em seu AndroidManifest.xml:

xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.yourapp">

    <!-- ... outras configurações do manifesto ... -->

    <!-- Adicione a configuração para ignorar a listagem de aplicativos -->
    <queries>
        <package android:name="com.example.app1" />
        <package android:name="com.example.app2" />
        <!-- Adicione mais pacotes de aplicativos aqui, se necessário -->
    </queries>

    <!-- ... outras configurações do manifesto ... -->

</manifest>

Essa configuração permite que seu aplicativo liste explicitamente os aplicativos específicos com os quais deseja interagir. Dessa forma, o Android 12 não solicitará que seu aplicativo liste todos os aplicativos com os quais interage, proporcionando uma experiência mais controlada em dispositivos com a API 31 ou superior.

Para mais informações e detalhes sobre as mudanças de visibilidade de pacotes no Android 12, consulte a documentação oficial do Android em: https://developer.android.com/about/versions/11/privacy/package-visibility.

Possíveis implementações

Handlers de notificação push

A seguir estão os métodos necessários para integrar corretamente as notificações push e mensagens In-App utilizando o Inngage, em conjunto com o Firebase Messaging.

• InngageNotificationMessage.registerSubscriber(String fcmToken):

Esse método deve ser chamado logo após InngageSDK.subscribe(). Ele envia o fcmToken do usuário para a API da Inngage, permitindo o recebimento de notificações push e mensagens In-App.

• InngageNotificationMessage.handlerNotificationForeground(...):

Esse método trata notificações recebidas com o app em primeiro plano. Ele deve ser utilizado dentro do listener FirebaseMessaging.onMessage.listen, conforme o exemplo abaixo:

Dart

FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
      final messageData = message.data;
      final hasInngageData = messageData.containsKey("inngageData") || messageData["provider"] == "inngage";

  if(hasInngageData){
    InngageNotificationMessage.handlerNotificationClick(remoteMessage: message);
  } else {
    _handlerCustomNotificationClick(message);
  }
});

📘

💡 As mensagens enviadas pela Inngage incluem no payload o campo provider: "inngage", permitindo a identificação e tratamento separado dentro do seu app.

• InngageNotificationMessage.handlerNotificationClick(...):

Este método deve ser chamado dentro do FirebaseMessaging.onMessageOpenedApp.listen, que é acionado quando o usuário clica em uma notificação com o app em segundo plano. Exemplo:

Dart

FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
      final messageData = message.data;
      final hasInngageData = messageData.containsKey("inngageData") || messageData["provider"] == "inngage";

  if(hasInngageData){
    InngageNotificationMessage.handlerNotificationClick(remoteMessage: message);
  } else {
    _handlerCustomNotificationClick(message);
  }
});

• InngageNotificationMessage.handlerNotificationClosed(...):

Esse método trata notificações recebidas com o app totalmente fechado (encerrado) e deve ser implementado no FirebaseMessaging.getInitialMessage():

Dart

FirebaseMessaging.instance.getInitialMessage().then((remoteMessage) {
      if (remoteMessage == null) return;

      final messageData = remoteMessage.data;
      final hasInngageData = messageData.containsKey("inngageData") || messageData["provider"] == "inngage";

      if (hasInngageData) {
        InngageNotificationMessage.handlerNotificationClosed(remoteMessage);
      } else {
        _handlerCustomNotificationClick(remoteMessage);
      }
    }).catchError((error) {
      debugPrint("Error on getInitialMessage: $error");
    });

• InngageNotificationMessage.handlerNotificationBackground(...):

Para garantir o funcionamento das mensagens In-App mesmo com o app em segundo plano, implemente o seguinte no FirebaseMessaging.onBackgroundMessage():

Dart

Future<void> _firebaseBackgroundHandler(RemoteMessage message) async {
  // seu código de tratamento...
    await InngageNotificationMessage.handlerNotificationBackground(remoteMessageData: message.data);
  }

E registre:

FirebaseMessaging.onBackgroundMessage(_firebaseBackgroundHandler);

---

✅ Conclusão

Com esses handlers devidamente implementados, você poderá utilizar os serviços da Inngage integrados ao Firebase Messaging — mesmo se o seu projeto utilizar outros serviços próprios de push notification. Isso garante compatibilidade, controle total do fluxo de mensagens e uso completo das funcionalidades de In-App Messaging da Inngage.