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

# Kotlin SDK (Android)

## Requisitos

* **minSdkVersion**: 21 (Android 5.0)
* **targetSdkVersion**: 34 (Android 14)
* **Kotlin version**: 1.8.22 ou superior
* **Java compatibilidade**: Java 8

## Instalação

Para instalar a Nemu SDK em sua aplicação construída com Kotlin é obrigatório adicionar a dependência do SDK em seu arquivo build.gradle.kts (ou .gradle), além disso adicionar as dependências para recuperar a origem em instalações de seu aplicativo no Google Play

```java theme={null}
repositories {
    mavenCentral()
}

dependencies {
    implementation("com.nemu:nemu-kotlin-sdk:1.0.0")
    /* Dependências para recuperação de origem através de instalação do app */

    // Google Play
    implementation ("com.android.installreferrer:installreferrer:2.2")
}
```

Após a instalação inicialize o nosso SDK no `onCreate` global da sua aplicação fornecendo o id do pixel da Nemu e a sua chave SDK Nemu como argumento

<Warning>
  Obs: Por medidas de segurança recomendamos que sua chave SDK Nemu esteja
  armazenada como variável de ambiente
</Warning>

Como sugestão você pode usar um plugin Gradle (como `dotenv-gradle`) para carregar um `.env` com conteúdo como:

```
SDK_TOKEN=<SDK_TOKEN>
PIXEL_ID=<PIXEL_ID>
```

E usar no `build.gradle.kts`:

```java theme={null}
val sdkToken = System.getenv("SDK_TOKEN") ?: "default"
val pixelId = System.getenv("PIXEL_ID") ?: "default"
buildConfigField("String", "SDK_TOKEN", "\"$sdkToken\"")
buildConfigField("String", "PIXEL_ID", "\"$pixelId\"")
```

Exemplo de inicialização da SDK no arquivo de entrada de uma aplicação mobile

```java theme={null}
import android.app.Application
import com.nemu.NemuTrackingLib
// ...
class MyApp: Application() {
    override fun onCreate() {
        super.onCreate()
        // ...
     // Utilização de variáveis de ambiente
NemuTrackingLib.getInstance().init(BuildConfig.PIXEL_ID, BuildConfig.SDK_TOKEN, this)
        // ...
    }
    // ...
}
```

Após esses passos a instalação da nossa SDK já estará completa em sua aplicação Kotlin

## 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, veja esse exemplo:

```java theme={null}
import com.nemu.NemuTrackingLib

fun AuthUserUseCase(email: String, password: String) {
    loginUser(
        email = email,
        password =password,
        onSuccess = { userId ->
            NemuTrackingLib.getInstance().setUserId(userId)

            Log.d("NemuTracking", "User registred: $userId")
        },
        onError = {
            Log.e("NemuTracking", "Error to login app: $userId")
        }
    )
}
```

Um ponto importante é que devemos garantir que os usuários já logados antes da instalação da SDK também sejam traqueados após a atualização, para isso você pode inserir o UID no momento em que ele se torna disponível em sua aplicação, como por exemplo no `onCreate()` da `Application` ou logo após carregar o usuário salvo (ex: Após `sessionManager.loadUser()`)

```java theme={null}
class MyApp: Application() {
override fun onCreate() {
            super.onCreate()

        // Verifica se o usuário está logado
            val userId = UserSessionManager.getCurrentUserId()
            if (userId != null) {
                NemuTrackingLib.getInstance().setUserId(userId)
            }
}
}
```

## 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, veja o exemplo abaixo:

```java theme={null}
import okhttp3.*
import org.json.JSONObject
import java.io.IOException
import com.nemu.NemuTrackingLib

fun sendPurchaseWithUtms() {
    val session = NemuTrackingLib.getInstance().getLastSessionHistory()

    val payload = JSONObject().apply {
        put("transactionId", "123")
        put("netValue", 10)
        put("status", "paid")
        put("utm_campaign", session?.utmCampaign ?: JSONObject.NULL)
        put("utm_content", session?.utmContent ?: JSONObject.NULL)
        put("utm_medium", session?.utmMedium ?: JSONObject.NULL)
        put("utm_source", session?.utmSource ?: JSONObject.NULL)
        put("utm_term", session?.utmTerm ?: JSONObject.NULL)
    }

    val client = OkHttpClient()
    val requestBody = payload.toString().toRequestBody("application/json".toMediaType())

    // Requisição para a Nemu API - POST - CREATE ORDER
    val request = Request.Builder()
        .url("https://developers.nemu.com.br/api/v1")
        .post(requestBody)
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onFailure(call: Call, e: IOException) {
            println("Error sending request: ${e.message}")
        }

        override fun onResponse(call: Call, response: Response) {
            println("API response: ${response.code}")
        }
    })
}
```

## Testando o SDK e garantindo de que está tudo certo

Para testar o fluxo completo e garantir de que a sua integração está funcionando corretamente você pode executar os simples passos abaixos:

### 1. Inicialize o SDK em modo de DEBUG

Para conseguir visualizar logs gerados pela própria SDK você pode ativá-lo passando o argumento opcional `isDebugMode` como `true` ao método de inicialização da SDK no lugar onde ele está sendo chamado

```java theme={null}
NemuTrackingLib.getInstance().init(BuildConfig.PIXEL_ID, BuildConfig.SDK_TOKEN, this, true) // Último argumento refere-se ao debugMode
```

### 2. Clique em um deeplink que redirecione para o aplicativo

Se a sua aplicação ainda não estiver configurada para receber deep links acesse [aqui para aprender como configurá-los](/pages/app-tracking/deeplinks)

Em sua ferramenta de emulação acesse um link que redirecione para o seu aplicativo com um conjunto de UTMs, exemplo: <br />
[https://myapp.com?utm\_source=nemu\&utm\_medium=medium-test\&utm\_campaign=campaign-test\&utm\_content=content-test](https://myapp.com?utm_source=nemu\&utm_medium=medium-test\&utm_campaign=campaign-test\&utm_content=content-test)

### 3. Acesse a sua aplicação e verifique se o SDK foi inicializado corretamente através dos logs

Após o aplicativo ser executado verifique os logs da sua aplicação, se tudo estiver configurado certo veremos os 3 logs abaixo

```
2025-05-22 14:55:02 [DEBUG] [NemuTracking] application has been successfully connected with Nemu services

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

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

#### Uma rápida explicação sobre cada log:

1. **Conexão com a Nemu:** Mostra que o SDK da Nemu conseguiu se conectar corretamente com os servidores da Nemu, através de pixel id e SDK token válidos
2. **Extração das UTMs:** Exibe que o SDK conseguiu receber e armazenar corretamente as UTMs definidas no DeepLink
3. **UID registado:** Informa que o SDK conseguiu atribuir o UID repassado ao acesso atual

### 4. Verifique se as UTMs estão sendo recuperadas corretamente ao chamar o método `getLastSessionHistory()`

Como último passo verifique se ao chamar o método `getLastSessionHistory()` as UTMs são recuperadas corretamente, com o modo de debug ativado você irá poder visualizar o objeto retornado nos logs mas pode adicionar de forma complementar logs no trecho onde o método está sendo executado para validações:

```java theme={null}
fun sendPurchaseWithUtms() {
    val session = NemuTrackingLib.getInstance().getLastSessionHistory()

    println("utmSource: ${session?.utmSource}")
    println("utmCampaign: ${session?.utmCampaign}")
    println("utmMedium: ${session?.utmMedium}")
    println("utmContent: ${session?.utmContent}")
    println("utmTerm: ${session?.utmTern}")
    // more code here...
}
```

No modo de debug ao chamar esse método o seguinte log irá ser retornado:

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

**Nota:** Note que no fim do utm\_content é inserido automaticamente a string `”||nemu_xiI85afzrP”`, essa string representa o identificador de sessão interno da Nemu e deve ser enviado como parte do utm\_content ao envio de vendas para a Nemu API