> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nemu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

1. Vá em **File > Add Packages...**
2. Insira a URL do repositório da SDK`https://github.com/nemu-brazil/nemu-swift-sdk.git`
3. 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):

```swift theme={null}
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:

```xml theme={null}
<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:

```swift theme={null}
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

<Info>
  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
</Info>

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:

```swift theme={null}
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

```swift theme={null}
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](/pages/app-tracking/deeplinks). 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:

```bash theme={null}
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:

1. **Conexão com a Nemu**: o SDK foi inicializado com sucesso e validou o token e pixel ID.
2. **Extração das UTMs**: o SDK leu e armazenou corretamente os parâmetros do deeplink.
3. **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.

```swift theme={null}
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.