Instalação

Ambiente de desenvolvimento

Antes de começar a utilizar nossa SDK, verifique se o seu ambiente de desenvolvimento possui o @ionic/cli , @angular/cli e o Apache Cordova, como estrutura de desenvolvimento do projeto.

Instalando a Inngage

A integração é feita em dois passos: primeiro instale o plugin nativo Cordova, responsável por Firebase, push notification e callbacks de clique; depois instale a SDK Ionic/TypeScript, usada pelo código do aplicativo.

1. Instale o plugin Cordova

Execute o comando abaixo na raiz do aplicativo Ionic/Cordova:

cordova plugin add cordova-plugin-inngage-firebase

Esse plugin adiciona a ponte nativa Android/iOS necessária para obter o token Firebase, receber pushes e identificar o clique em notificações com o app aberto, em segundo plano ou fechado.

2. Instale a SDK Ionic

Em seguida, instale o pacote da SDK:

npm i @inngageregistry/inngageionic

Esse pacote expõe as classes Inngage e InngageNotificationMessage, além dos tipos e erros usados na integração.

Depois da instalação, o package.json do aplicativo deve conter entradas equivalentes a:

"dependencies": {
  "@inngageregistry/inngageionic": "^2.0.0",
  "@awesome-cordova-plugins/app-version": "^9.2.0",
  "@awesome-cordova-plugins/device": "^9.2.0",
  "@awesome-cordova-plugins/local-notifications": "^9.2.0",
  "@awesome-cordova-plugins/globalization": "^9.2.0",
  "@awesome-cordova-plugins/in-app-browser": "^9.2.0"
},
"devDependencies": {
  "cordova-plugin-inngage-firebase": "^1.0.0"
}

📘
Importante: a SDK @inngageregistry/inngageionic não substitui o plugin Cordova. O plugin precisa estar instalado no aplicativo para que as funcionalidades nativas de Firebase e notificações funcionem.

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.

Inclusão da dependência

Após instalar a SDK, importe-a no seu projeto. A exportação padrão é Inngage e InngageNotificationMessage é exportado como named export:

import Inngage, { InngageNotificationMessage } from '@inngageregistry/inngageionic';

Para tratamento de erros tipados, importe também as classes de erro:

import Inngage, {
  InngageNotificationMessage,
  FirebaseUnavailableError,
  PermissionDeniedError,
  NetworkError,
} from '@inngageregistry/inngageionic';

🚧
Recomendamos que você utilize a versão estável do Ionic, definida no arquivo package.json. A SDK foi verificada pela última vez na versão: Ionic 7 / Angular 17 / Cordova 12 • canal estável.
Versões suportadas:
"Ionic CLI": "7.2.0", "Angular CLI": "17.3.11" e "Cordova CLI": "12.0.0"

Implementando a SDK

📘
Caso queiram verificar os logs da Inngage enquanto estão desenvolvendo, basta implementar no seu código o método Inngage.setDebugMode(true).

Inngage.configure()

Configure a SDK assim que o aplicativo iniciar, antes de registrar os listeners de notificação. Isso garante que cliques em push durante cold start tenham appToken e ambiente corretos para confirmar o clique na API /notification/.

Inngage.configure({
  appToken: 'Adicionar o App Token do aplicativo',
  dev: false,
  debugMode: true,
});

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.

Inngage.subscribe()

Esta função registra ou inscreve o usuário na plataforma Inngage. Ela solicita permissão de notificações push, obtém o token Firebase, coleta informações do dispositivo e envia a inscrição para a API.

async subscribe() {
  try {
    await Inngage.subscribe({
      appToken: "Adicionar o App Token do aplicativo",
      friendlyIdentifier: "[email protected]",
      customFields: {
        "name": "Saulo",
        "age": 27,
        "login": "inativo"
      }
    });
  } catch (error) {
    if (error instanceof FirebaseUnavailableError) {
      console.error("Plugin Firebase não está disponível.");
    } else if (error instanceof PermissionDeniedError) {
      console.error("Usuário negou permissão de notificações.");
    } else if (error instanceof NetworkError) {
      console.error("Falha na comunicação com a API:", error.message);
    } else {
      console.error("Erro inesperado:", error);
    }
  }
}

Explicação dos parâmetros:

appToken: Token do aplicativo na plataforma Inngage (obrigatório).
friendlyIdentifier: Identifica o usuário de forma única (ex.: e-mail ou CPF).
customFields: Campos personalizados em forma de chave-valor, como nome, idade, etc.
phoneNumber: (Opcional) Número de telefone do usuário.
email: (Opcional) E-mail do usuário.
dev: (Opcional) true para utilizar o endpoint de staging/desenvolvimento.

📘
Recomendamos que esse método seja chamado a cada nova sessão do usuário para assegurar rastreabilidade.

InngageNotificationMessage.notificationMessage()

Essa função registra os listeners de mensagens FCM e o callback de clique da notificação:

InngageNotificationMessage.notificationMessage(
  (payload) => {
    if (payload != null) {
      console.log('Notificação recebida:', payload);
    }
  },
  'res://ic_notification', // (Opcional) ícone de notificação Android
  (payload) => {
    console.log('Usuário clicou na notificação:', payload);
  }
);

Parâmetros:

firebaseListenCallback: (Opcional) Callback invocado a cada payload de notificação recebido.
notificationIcon: (Opcional) Nome do recurso de ícone pequeno para notificações Android em primeiro plano (ex.: 'res://ic_notification').
notificationClickCallback: (Opcional) Callback invocado quando o usuário toca na notificação, com o app aberto, em segundo plano ou fechado.

📘
No método ngOnInit() ou após platform.ready(), adicione os métodos configurados da Inngage.

Alterando ícone de notificação em primeiro plano

Passe o nome do ícone como segundo parâmetro de notificationMessage():

InngageNotificationMessage.notificationMessage(undefined, 'res://ic_notification');

Certifique-se de que o ícone esteja presente em platforms/android/app/src/main/res.

Atualização de dados do usuário

Inngage.addUserData()

Permite atualizar campos personalizados de um usuário já inscrito sem precisar realizar uma nova subscription:

async updateUser() {
  try {
    await Inngage.addUserData({
      identifier: "[email protected]",
      customFields: {
        "plan": "premium",
        "last_purchase": "2024-01-15"
      },
      phoneNumber: "+5511999999999",
      email: "[email protected]"
    });
  } catch (error) {
    console.error("Erro ao atualizar dados do usuário:", error);
  }
}

Campos:

identifier: Identificador único do usuário (obrigatório).
customFields: Campos personalizados a serem atualizados.
phoneNumber: (Opcional) Número de telefone.
email: (Opcional) E-mail.
dev: (Opcional) true para utilizar o endpoint de staging/desenvolvimento.

Envio de eventos

A SDK permite o envio de eventos customizados. Eles devem ser previamente configurados na plataforma Inngage.

onClickEvent() {
  let event = {
    eventName: "ionic_event",
    conversionEvent: true,
    conversionValue: 1090.00,
    conversionNotId: "2314klbkf41bsgav4hg12ab24v1h41",
    eventValues: {
      "nome_sdk": 'Inngage Ionic',
      "valor": '40'
    }
  }
  Inngage.sendEvent(event);
}

Campos:

eventName: Nome do evento (obrigatório).
eventValues: Dados adicionais em forma de chave-valor.
conversionEvent: Define se é um evento de conversão.
conversionValue: Valor monetário da conversão (float).
conversionNotId: ID único da notificação push que originou a conversão.
dev: (Opcional) true para utilizar o endpoint de staging/desenvolvimento.

Tratamento de erros

A SDK expõe classes de erro tipadas para facilitar o tratamento diferenciado de falhas:

Classe	Quando é lançada
`FirebaseUnavailableError`	O plugin `cordova-plugin-inngage-firebase` não está disponível ou o dispositivo ainda não está pronto.
`PermissionDeniedError`	O usuário negou a permissão de notificações push.
`TokenError`	Não foi possível obter o token Firebase do dispositivo.
`NetworkError`	Uma requisição HTTP falhou (erro de rede ou resposta não-2xx). Contém a propriedade `statusCode` quando disponível.

Todas as classes herdam de InngageError, que por sua vez herda de Error.

Deep Links

A SDK trata automaticamente os deep links recebidos nos payloads de notificação. O campo type do payload controla o comportamento:

"inapp": abre a URL em um browser in-app (In-App Browser).
"deep": abre a URL via browser do sistema ou handler de deep link nativo.

👍
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. 👏

Ionic Cordova SDK 2.0.0

Instalação

Ambiente de desenvolvimento

Instalando a Inngage

1. Instale o plugin Cordova

2. Instale a SDK Ionic

Importante: a SDK `@inngageregistry/inngageionic` não substitui o plugin Cordova. O plugin precisa estar instalado no aplicativo para que as funcionalidades nativas de Firebase e notificações funcionem.

Importando o FCM Token (API Key)

Inclusão da dependência

Recomendamos que você utilize a versão estável do Ionic, definida no arquivo package.json. A SDK foi verificada pela última vez na versão: Ionic 7 / Angular 17 / Cordova 12 • canal estável.

Implementando a SDK

Caso queiram verificar os logs da Inngage enquanto estão desenvolvendo, basta implementar no seu código o método `Inngage.setDebugMode(true)`.

Inngage.configure()

Notificações push

Inngage.subscribe()

Recomendamos que esse método seja chamado a cada nova sessão do usuário para assegurar rastreabilidade.

InngageNotificationMessage.notificationMessage()

No método `ngOnInit()` ou após `platform.ready()`, adicione os métodos configurados da Inngage.

Alterando ícone de notificação em primeiro plano

Atualização de dados do usuário

Inngage.addUserData()

Envio de eventos

Tratamento de erros

Deep Links

Você está pronto para começar!

Instalação

Ambiente de desenvolvimento

Instalando a Inngage

1. Instale o plugin Cordova

2. Instale a SDK Ionic

Importante: a SDK @inngageregistry/inngageionic não substitui o plugin Cordova. O plugin precisa estar instalado no aplicativo para que as funcionalidades nativas de Firebase e notificações funcionem.

Importando o FCM Token (API Key)

Inclusão da dependência

Recomendamos que você utilize a versão estável do Ionic, definida no arquivo package.json. A SDK foi verificada pela última vez na versão: Ionic 7 / Angular 17 / Cordova 12 • canal estável.

Implementando a SDK

Caso queiram verificar os logs da Inngage enquanto estão desenvolvendo, basta implementar no seu código o método Inngage.setDebugMode(true).

Inngage.configure()

Notificações push

Inngage.subscribe()

Recomendamos que esse método seja chamado a cada nova sessão do usuário para assegurar rastreabilidade.

InngageNotificationMessage.notificationMessage()

No método ngOnInit() ou após platform.ready(), adicione os métodos configurados da Inngage.

Alterando ícone de notificação em primeiro plano

Atualização de dados do usuário

Inngage.addUserData()

Envio de eventos

Tratamento de erros

Deep Links

Você está pronto para começar!

Importante: a SDK `@inngageregistry/inngageionic` não substitui o plugin Cordova. O plugin precisa estar instalado no aplicativo para que as funcionalidades nativas de Firebase e notificações funcionem.

Caso queiram verificar os logs da Inngage enquanto estão desenvolvendo, basta implementar no seu código o método `Inngage.setDebugMode(true)`.

No método `ngOnInit()` ou após `platform.ready()`, adicione os métodos configurados da Inngage.