Swift SDK (IOS)

Requerimentos

iOS Alvo: 13+
Versão Swift: 5.1
Xcode mínimo: XCode 11

Instalação

Para instalar a nossa SDK em sua aplicação Swift há 2 opções:

Pelo XCode (Recomendado)

Vá em File > Add Packages…
Insira a URL do repositório da SDKhttps://github.com/nemu-brazil/nemu-swift-sdk.git
Escolha a versão From 1.0.0

O Xcode vai importar automaticamente a biblioteca e permitir a importação: import NemuTrackingLib

Ou via Package.swift (Quando usando SPM no manifesto):

dependencies: [
    .package(url: "https://github.com/sua-org/MyTrackingSDK.git", from: "1.0.0")
]

Após a inclusão da SDK no projeto, inicialize o SDK em seu arquivo principal da aplicação passando como argumento o id do pixel da Nemu e a sua chave SDK Nemu ⚠️ Obs: Por medidas de segurança recomendamos que sua chave SDK Nemu esteja armazenada como variável de ambiente Como recomendação podemos usar o Info.plist para encontrá-lo acesse: configurações no build (Xcode) → Info.plist No seu Info.plist, adicione:

<key>SDK_TOKEN</key>
<string>my-secret-sdk-token</string>

<key>PIXEL_ID</key>
<string>my-pixel-id</string>

Em seu código adicione as variáveis de ambiente como no exemplo abaixo:

import UIKit
import NemuTrackingLib

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let sdkKey = Bundle.main.object(forInfoDictionaryKey: "SDK_TOKEN") as? String
    let pixelId = Bundle.main.object(forInfoDictionaryKey: "PIXEL_ID") as? String

        NemuTrackingManager.shared.initialize(widthPixelId: pixelId, withSdkKey: sdkKey)

        return true
    }

    // outros métodos...
}

Registrar UID a sessão do SDK

Para total segurança e integridade dos dados de usuários de sua aplicação, todos os UID registrados pelo nosso SDK são criptografados antes de serem armazenados em nossos servidores

Durante o processo de login da aplicação adicione uma chamada ao método setUserId() passando como argumento o UID definido do usuário que acabou de realizar o processo de login, exemplo:

import Foundation
import NemuTrackingLib

func authenticateUser(email: String, password: String) {
    loginUser(
        email: email,
        password: password,
        onSuccess: { userId in
            TrackingManager.shared.setUserId(userId)
            print("NemuTracking: User registered: \(userId)")
        },
        onError: {
            print("NemuTracking: Failed to authenticate user.")
        }
    )
}

É importante garantir que usuários que já estavam logados antes da instalação ou atualização do SDK também sejam corretamente traqueados. Para isso, você pode definir o UID assim que ele estiver disponível na aplicação normalmente logo após o carregamento do usuário salvo localmente.

Exemplo: Aplicações UIKit com AppDelegate

No AppDelegate, após recuperar o usuário da sessão (por exemplo, via UserSessionManager), chame o método setUserId do SDK:

import UIKit
import NemuTrackingLib

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Recupera o usuário logado, se houver
        if let userId = UserSessionManager.shared.currentUserId {
            NemuTrackingManager.shared.setUserId(userId)
        }

        return true
    }
}

Recuperar UTMs ao enviar disparo de venda para a API da Nemu

O método getLastSessionHistory() retorna um objeto contendo as UTMs da última sessão do usuário, utilize esse objeto ao enviar as informações da venda a API da Nemu

import Foundation
import NemuTrackingLib

func sendPurchaseWithUtms() {
    guard let session = TrackingManager.shared.getLastSessionHistory() else {
        print("No session found")
        return
    }

    let payload: [String: Any?] = [
        "transactionId": "123",
        "netValue": 10,
        "status": "paid",
        "utm_campaign": session.utmCampaign ?? NSNull(),
        "utm_content": session.utmContent ?? NSNull(),
        "utm_medium": session.utmMedium ?? NSNull(),
        "utm_source": session.utmSource ?? NSNull(),
        "utm_term": session.utmTerm ?? NSNull()
    ]

    guard let url = URL(string: "https://developers.nemu.com.br/api/v1") else {
        print("Invalid URL")
        return
    }

    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")

    do {
        request.httpBody = try JSONSerialization.data(withJSONObject: payload, options: [])
    } catch {
        print("Failed to serialize JSON: \(error.localizedDescription)")
        return
    }

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if let error = error {
            print("Error sending request: \(error.localizedDescription)")
            return
        }

        if let httpResponse = response as? HTTPURLResponse {
            print("API response: \(httpResponse.statusCode)")
        }
    }

    task.resume()
}

Testando o SDK e garantindo que está tudo certo – SDK Swift

Para testar o fluxo completo de integração e garantir que tudo está funcionando corretamente com a SDK da Nemu em Swift, siga os passos abaixo:

1. Inicialize o SDK em modo Debug

Para visualizar logs detalhados da SDK, ative o modo de debug ao inicializá-la. Basta passar o parâmetro isDebugMode como true no momento da inicialização:

NemuTrackingManager.shared.initialize(
    withPixelId: "YOUR_PIXEL_ID",
    withApiKey: "YOUR_SDK_TOKEN",
    isDebugMode: true
)

⚠️ Certifique-se de chamar esse método no início da aplicação, por exemplo no AppDelegate ou na struct @main do SwiftUI.

2. Clique em um deeplink que redirecione para o app com UTMs

Se a sua aplicação ainda não estiver configurada para receber deep links, siga nosso guia para configurar Universal Links no iOS. Use um link como este (com UTMs) para realizar o teste:

https://myapp.com?utm_source=nemu&utm_medium=medium-test&utm_campaign=campaign-test&utm_content=content-test

Você pode simular o acesso no Safari do dispositivo ou em um terminal com o comando:

xcrun simctl openurl booted "https://myapp.com?utm_source=nemu&utm_medium=medium-test&utm_campaign=campaign-test&utm_content=content-test"

3. Verifique os logs da aplicação

Com o SDK corretamente configurado e o modo debug ativado, você deverá visualizar os seguintes logs no console ao abrir o app via deeplink:

2025-05-22 14:55:02 [DEBUG] [NemuTracking] Application successfully connected with Nemu services

2025-05-22 14:55:03 [DEBUG] [NemuTracking] UTM parameters successfully extracted from deeplink - {"utm_source": "nemu","utm_medium": "medium-test","utm_campaign": "campaign-test","utm_content": "content-test"}

2025-05-22 14:56:00 [DEBUG] [NemuTracking] UID registered by the application - { "userId": "example@email.com" }

Explicação dos logs:

Conexão com a Nemu: o SDK foi inicializado com sucesso e validou o token e pixel ID.
Extração das UTMs: o SDK leu e armazenou corretamente os parâmetros do deeplink.
UID registrado: o app passou o identificador único do usuário usando setUserId.

4. Verifique a recuperação das UTMs com `getLastSessionHistory()`

Como passo final, chame o método getLastSessionHistory() e valide se os dados das UTMs estão sendo recuperados corretamente.

func sendPurchaseWithUtms() {
    guard let session = TrackingManager.shared.getLastSessionHistory() else {
        print("No sessions found")
        return
    }

    print("utmSource: \(session.utmSource ?? "nil")")
    print("utmCampaign: \(session.utmCampaign ?? "nil")")
    print("utmMedium: \(session.utmMedium ?? "nil")")
    print("utmContent: \(session.utmContent ?? "nil")")
    print("utmTerm: \(session.utmTerm ?? "nil")")
}

No modo debug, o SDK também imprime automaticamente:

2025-05-22 15:00:02 [DEBUG] [NemuTracking] Last session history retrieved - {"utm_source": "nemu","utm_medium": "medium-test","utm_campaign": "campaign-test","utm_content": "content-test||nemu_xiI85afzrP"}

Nota: O valor "||nemu_xiI85afzrP" no final do utm_content é o identificador interno de sessão da Nemu. Ele deve ser enviado exatamente assim ao registrar vendas na Nemu API.

​Requerimentos

​Instalação

​Pelo XCode (Recomendado)

​Ou via Package.swift (Quando usando SPM no manifesto):

​Registrar UID a sessão do SDK

​Exemplo: Aplicações UIKit com AppDelegate

​Recuperar UTMs ao enviar disparo de venda para a API da Nemu

​Testando o SDK e garantindo que está tudo certo – SDK Swift

​1. Inicialize o SDK em modo Debug

​2. Clique em um deeplink que redirecione para o app com UTMs

​3. Verifique os logs da aplicação

​Explicação dos logs:

​4. Verifique a recuperação das UTMs com getLastSessionHistory()

Requerimentos

Instalação

Pelo XCode (Recomendado)

Ou via Package.swift (Quando usando SPM no manifesto):

Registrar UID a sessão do SDK

Exemplo: Aplicações UIKit com AppDelegate

Recuperar UTMs ao enviar disparo de venda para a API da Nemu

Testando o SDK e garantindo que está tudo certo – SDK Swift

1. Inicialize o SDK em modo Debug

2. Clique em um deeplink que redirecione para o app com UTMs

3. Verifique os logs da aplicação

Explicação dos logs:

4. Verifique a recuperação das UTMs com `getLastSessionHistory()`