Guides
GuidesAPI ReferenceHome

iOS SDK Swift Package

Suggest Edits

📘

A versão mais recente da SDK iOS Swift é a v1.0.1, 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.subscribe(...)

Esse função deve ser chamada para enviar os dados do usuário e campos personalizados para a Inngage. Você pode usá-lo em seu projeto no .onAppear ou no init(). Isso é ideal para inicialização quando a View aparece na tela. 

let appToken = "Adicionar pelo seu app token da Inngage"
let identifier = "Adicionar um identificador do usuario"
let email = "[email protected]"
let phoneNumber = "11999999999"
let customFields: [String: Any] = [
  "nome": "User 01",
  "dt_nascimento": "01/09/1970",
  "genero": "M",
  "cartao": "N",
  "ultimo_abastecimento": "10/09/2018",
  "total_abastecido": "290,00"
]

InngageSDK.shared.subscribe(
  appToken: appToken,
  identifier: identifier,
  email: email,
  phoneNumber: phoneNumber,
  customFields: customFields,
	requestGeolocation: true
)

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

Com os dados já enviados, agora será necessário obter o token FCM para finalizar o envio para nossa API de subscription. Para isso, você deve obter o token através do método messaging (_:didReceiveRegistrationToken:) no AppDelegate.

Como o token FCM nem sempre está disponível de imediato, você pode usá-lo no .onChange para escutar quando ele estiver pronto. Assim que o token for atualizado, o registerSubscriber é chamado com o token correto.

.onChange(of: deviceTokenManager.fcmToken) { newToken in
    guard let token = newToken else { return }
    print("✅ Token FCM pronto! Chamando registerSubscriber...")
    InngageSDK.shared.registerSubscriber(token: token)
}

InngageSDK.shared.updateStatusNotification(...)

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
  InngageSDK.shared.updateStatusNotification(data: userInfo)
  completionHandler()
}

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.

👍

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