Guides
GuidesAPI ReferenceHome

iOS SDK Swift Package

Suggest Edits

📘

A versão mais recente da SDK iOS Swift é a v2.0.0, que está disponível atualmente.

Passos iniciais

  1. Configuração Firebase
  2. Configuração painel Inngage (passo 3 do link)

Instalação

Instalando o package pelo Swift Package Manager

Para instalar o package da Inngage em seu projeto Swift, basta seguir os passos para adicionar como qualquer outro package:

  1. Com o Xcode aberto, clique em File;
  2. Clique em Add Package Dependencies...;
  3. Procure nosso package pelo repositório: https://github.com/inngage/inngage-ios-swift.
  4. Selecione o projeto em Add to Project;
  5. Clique em Add Package;
  6. Selecione o target do projeto do aplicativo em Add to Target;
  7. Clique novamente em Add Package;

👍

A SDK da Inngage Swift já está disponível em seu projeto.

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.shared.registerSubscriber(...)

Essa função deve ser chamada para enviar os dados do usuário e campos personalizados para a Inngage, desta forma os usuários do aplicativo serão cadastrados em nossa base. 

let appToken = "4274b9fb641c0a021f27776ff21fc148"
let identifier = "[email protected]"
let email = "[email protected]"
let phoneNumber = "11988888888"
let customFields: [String: Any] = [
  "nome": "User 01",
  "dt_nascimento": "01/09/1970",
  "genero": "M",
  "possui_cartao": true,
  "idade": 10
]

await InngageSDK.shared.registerSubscriber(
	appToken: appToken,
  identifier: identifier,
  fcmToken: token, // Token do Firebase
  email: email,
  phoneNumber: phoneNumber,
  customFields: customFields,
  requestGeolocation: false
)

O trecho de código menciona alguns parâmetros e funcionalidades da SDK Inngage. 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.
  • identifier: É 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.
  • fcmToken: É o token do Firebase. Para obtê-lo use o método messaging (_:didReceiveRegistrationToken:) no AppDelegate.
  • requestGeolocation: 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.
  • 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.
  • customFields: Caso deseja adicionar mais dados complementares do usuário para utilizá-los em nossa plataforma, como nome, cidade, etc.

InngageSDK.shared.handleNotificationInteraction(...)

Quando os usuários do aplicativo interagirem com a notificação clicando em qualquer cenário (aberto, segundo plano ou fechado), esta função irá atualizar o status de Enviado para Aberto. Caso queira averiguar o status das notificações, na plataforma web da Inngage busque a tela de Enviados que você conseguirá obter essa informação. Nossa função deve estar dentro do método userNotificationCenter (_:didReceive:withCompletionHandler:) no AppDelegate, conforme exemplificado abaixo:

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {
  let userInfo = response.notification.request.content.userInfo
  Task {
		await Inngage.shared.handleNotificationInteraction(data: userInfo)
	}
  completionHandler()
}

Caso a notificação push enviada estiver configurado com o weblink ou deeplink, será aberto um browser com o link adicionado em nossa plataforma web.

Personalização (para a 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.

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 requestGeolocation disponível no InngageSDK.shared.subscribe(...):

Enviando dados UTM para o Google Analytics

Agora, é possível enviar os parâmetros UTM configurados após o clique da notificações push pela plataforma diretamente para o Google Analytics no AppDelegate:

if let utmEvent = InngageAnalytics.extractUTMEvent(from: userInfo){
  print("✅ Enviar evento: \(utmEvent.name), params: \(utmEvent.parameters)")
  Analytics.logEvent(utmEvent.name, parameters: utmEvent.parameters)
} else {
  print("🔕 UTM inválido, nada será enviado")
}

O código acima deve estar dentro do método userNotificationCenter (_:didReceive:withCompletionHandler:).

Envio de eventos

A SDK permite que o desenvolvedor que está integrando a SDK envie eventos customizados das ações do usuário em seu aplicativo. É importante configurá-los na plataforma Inngage para garantir a integração.

let appToken = "Adicionar pelo seu app token da Inngage"
let identifier = "Adicionar um identificador do usuario"
let eventValues: [String: Any] = [
  "nome": "User 01",
  "dt_nascimento": "01/09/1970",
  "genero": "M",
  "cartao": "N",
  "ultimo_abastecimento": "10/09/2018",
  "total_abastecido": "290,00"
]
let conversionEvent = true
let conversionValue = 10.0
let conversionNotId = "2314klbkf41bsgav4hg12ab24v1h41"

InngageSDK.shared.sendEvent(
  eventName: "Adicionar o nome do evento"
  appToken: appToken,
  identifier: identifier,
  eventValues: eventValues,
  conversionEvent: conversionEvent,
  conversionValue: conversionValue,
	conversionNotId: conversionNotId
)

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 Swift da Inngage possibilita a exibição de Mensagens In-App para os usuários. Essas mensagens são pushs silenciosos e podem ser enviados tanto pela plataforma quanto pela API. São automaticamente apresentadas com base nas configurações recebidas pelo payload do Firebase.

Para apresentar a mensagem In-App, deve configurar o AppDelegate e o ContentView que irá abri-la. Este fluxo permite que o aplicativo receba um push silencioso (com conteúdo para In App Message), e exiba uma interface interativa dentro do app, em tempo real, com botões e callbacks customizados.

Configurar o método de Push Silencioso no AppDelegate

No método application(_:didReceiveRemoteNotification:fetchCompletionHandler:), adicione o seguinte código:

func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    print("📩 Push silencioso recebido: \(userInfo)")
    
    // Notifica a ContentView para exibir o In-App
    NotificationCenter.default.post(
        name: NSNotification.Name("ShowInAppView"),
        object: nil,
        userInfo: userInfo
    )
    
    completionHandler(.newData)
}

Isso garante que qualquer notificação com conteúdo para In-App poderá ser tratada e renderizada na UI.

Configurar o ContentView para escutar e exibir o In-App

O componente .onAppear escuta o evento configurado no AppDelegate e atualiza os @State para exibir o In App. Quando o showInAppView for atualizado para true, o componente visual InngageInApp(...) irá renderizar a interface do In App Message conforme os dados recebidos no notificationData. 

struct ContentView: View {
    @State private var showInAppView = false
    @State private var notificationData: [String: Any]?

    var body: some View {
        ZStack {
            VStack {
                Text("Exemplo In App Message")
            }

            // Exibe o In-App se showInAppView for true
            if showInAppView {
                InngageInApp(
                    data: notificationData ?? [:],
                    isShowing: $showInAppView,
                    actionButtonRight: {
                        print("Clicou no botão direito")
                    },
                    actionButtonLeft: {
                        print("Clicou no botão esquerdo")
                    },
                    onDismissed: {
                        print("In-App Message fechada")
                    }
                )
            }
        }
        .onAppear {
            // Escuta notificações de push silencioso com In-App
            NotificationCenter.default.addObserver(
                forName: NSNotification.Name("ShowInAppView"),
                object: nil,
                queue: .main
            ) { notification in
                if let userInfo = notification.userInfo as? [String: Any] {
                    notificationData = userInfo
                }
                showInAppView = true
            }
        }
    }
}

Temos alguns callbacks definidos para ações no In-App:

  • actionButtonLeft/Right: Callbacks definidos pelo cliente para ações específicas dos botões do In-App.
  • onDismissed: Callback chamado quando o usuário fecha ou ignora o In-App.

📘

Mesmo que seu aplicativo não utilize SwiftUI, ainda é possível exibir o componente InngageInApp, que foi implementado em SwiftUI, em qualquer tela do seu app UIKit de forma simples e transparente.

Renderizando as In-App Message com UIHostingController

A Apple oferece uma classe chamada UIHostingController, que permite renderizar views SwiftUI dentro de um ambiente UIKit. Assim, você pode incorporar o InngageInApp como se fosse uma view comum, sem precisar migrar seu projeto para SwiftUI.

Se você tem uma UIViewController padrão (por exemplo, HomeViewController, MainViewController, etc.) e deseja exibir a mensagem In-App:

  • Não precisa apresentar um modal.
  • Não precisa mudar a estrutura do seu app.
  • Basta injetar a tela do In-App como uma camada visual por cima da tela atual, com suporte a clique nos botões e dismiss automático.

👍

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

Updated 2 days ago