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

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

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

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:

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

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

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

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

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:

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

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 Em sua ferramenta de emulação acesse um link que redirecione para o seu aplicativo com um conjunto de UTMs, exemplo:
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:

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
Extração das UTMs: Exibe que o SDK conseguiu receber e armazenar corretamente as UTMs definidas no DeepLink
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:

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

​Requisitos

​Instalação

​Registrar UID a sessão do SDK

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

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

​1. Inicialize o SDK em modo de DEBUG

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

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

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

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

Requisitos

Instalação

Registrar UID a sessão do SDK

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

Testando o SDK e garantindo de que está tudo certo

1. Inicialize o SDK em modo de DEBUG

2. Clique em um deeplink que redirecione para o aplicativo

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

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

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