SDK para Android

Kotlin, que também pode ser chamado a partir de Java. O SDK depende apenas da biblioteca Play Install Referrer do Google e do lifecycle-process do AndroidX. Plano Pro ou superior.

Requisitos

• Android 6.0+ (minSdk 23).
• Kotlin ou Java.
• Uma chave do SDK: no painel, abra seu app → Configurações → Chaves do SDK → Nova chave. Ela aparece uma única vez, então copie-a nesse momento.

Instalação

O SDK está no Maven Central, que todo projeto Android novo já usa. Adicione uma linha ao módulo do app e sincronize o Gradle:

// app/build.gradle.kts
dependencies {
    implementation("dev.unolink:unolink:0.3.3")
}

Configuração

Chame configure uma vez, na sua classe Application, antes que qualquer outra coisa rode:

import dev.unolink.Unolink

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Unolink.configure(this, "ulk_…")
    }
}

Ainda não tem uma classe Application? Crie esta e registre-a no AndroidManifest.xml:

<application android:name=".MyApp" …>

Java:

public class MyApp extends Application {
    @Override public void onCreate() {
        super.onCreate();
        Unolink.configure(this, "ulk_…");
    }
}

Opções

Passe UnolinkOptions como terceiro argumento. Todos os campos são opcionais.

Unolink.configure(this, "ulk_…", UnolinkOptions(
    logLevel = LogLevel.DEBUG,
    debug = true,
))

A chave é pública: ela vai dentro do seu app e só pode reportar dados desse app. Veja Chaves do SDK.

Eventos do funil

Adicione uma linha em cada momento importante. Elas viram as etapas em Funil e Jornadas.

Unolink.onboardingCompleted()                 // the last onboarding screen is done
Unolink.paywallViewed("onboarding")           // a paywall appeared; placement says which one
Unolink.paywallSkipped("onboarding")          // closed without buying
Unolink.signUp("email")                       // an account was created
Unolink.signUpSkipped()                       // went on as a guest (0.3.2+)

Sem RevenueCat, reporte você mesmo os testes grátis e as compras. O valor é um BigDecimal, então os preços nunca são arredondados:

Unolink.trialStarted(productId = "pro_yearly")
Unolink.purchase(BigDecimal("49.99"), "USD", productId = "pro_yearly")
Unolink.purchaseCancelled(productId = "pro_yearly")   // closed the purchase sheet
Unolink.purchaseFailed(productId = "pro_yearly", reason = "card_declined")

Seus próprios eventos recebem um nome e até 20 propriedades:

Unolink.track("level_up", mapOf("level" to 3))

A lista completa, com os nomes que chegam ao painel, está em Eventos.

ID de usuário e RevenueCat

Se você usa RevenueCat, conecte-o no seu app → Configurações → RevenueCat. Depois disso, não chame purchase nem trialStarted: o próprio RevenueCat envia testes grátis, compras, renovações, cancelamentos e reembolsos, e o Unolink ignora as chamadas de compra do app para que nada conte duas vezes.

Para ligar essas compras à instalação, informe o próprio app user ID do RevenueCat. Com o SDK 0.3.2 ou posterior, uma linha o mantém atualizado. Chame-a uma vez na abertura, antes ou depois de configure:

Unolink.connectRevenueCat { Purchases.sharedInstance.appUserID }

O Unolink lê o ID na abertura, sempre que o app vai para o primeiro plano e antes de cada evento, e só o envia quando ele mudou. Se o RevenueCat ainda não estiver configurado, a leitura falha em silêncio e é tentada de novo depois. Depois de Purchases.sharedInstance.logIn e logOut, chame Unolink.revenueCatUserChanged() para enviar o novo ID na hora.

Sem ela (ou antes da 0.3.2), chame setUserId com o ID do RevenueCat depois de Purchases.configure, depois de cada Purchases.logIn e Purchases.logOut, e em toda abertura. Use um ou outro, não os dois:

// after Purchases.configure, logIn and logOut, and on every launch
Unolink.setUserId(Purchases.sharedInstance.appUserID)

Para um convidado, esse é o ID anônimo do RevenueCat, então uma compra feita antes do cadastro se junta à instalação na hora. Depois do logIn, é o ID da conta. Todo ID que uma instalação reportou conta, então a compra do convidado continua ligada. Veja Convidados e contas.

O Unolink nunca guarda o ID em si, apenas um hash unidirecional que é diferente para cada um dos seus apps.

Deep links adiados

Quando alguém toca em um link do Unolink no Android, instala pelo Google Play e abre o app, o SDK lê o referrer de instalação do Play e chama seu listener uma vez, na thread principal. Defina o Deep link e os Parâmetros do link no painel (Links → ⋯ → Editar).

Unolink.setDeferredDeepLinkListener { link ->
    // link.deepLink: "/promo/3for2" or "myapp://promo/3for2", or null
    // link.params:   mapOf("offer" to "3for2")
    // link.linkSlug: "tiktok", or null for your app's main link
    // link.clickId:  "clk_01JA…"
    link.deepLink?.let { navigate(it) }
    Unolink.consumeDeferredDeepLink()
}

O listener é chamado uma vez por instalação. Registre-o logo após configure, ou depois: um link que chegou antes do registro continua sendo entregue, inclusive em uma abertura posterior se nenhum listener tinha sido definido antes.

Abrir depois do onboarding

A primeira abertura geralmente começa no onboarding. Se a tela do link fica depois do onboarding ou do login, não a abra pelo listener. Quando o onboarding (ou o login) terminar, leia o link pendente, abra-o e depois marque-o como consumido:

// when onboarding (or sign-in) is done, and on every launch after that until it's consumed
Unolink.getPendingDeferredDeepLink()?.let { link ->
    link.deepLink?.let { navigate(it) }
    Unolink.consumeDeferredDeepLink()
}

O link espera até você consumi-lo, mesmo que o app seja fechado nesse meio-tempo (até 30 dias depois da instalação; 0.3.3+). Um usuário novo que sai no meio do onboarding ainda o recebe na próxima abertura, então você não precisa guardá-lo. Chame consumeDeferredDeepLink() depois de abri-lo: até lá, getPendingDeferredDeepLink() o retorna a cada abertura. Ele é null antes de configure e até o Google Play responder (um ou dois segundos na primeira abertura).

Para testar sem uma instalação pelo Play, use debugInstallReferrer (veja Testes). Como o referrer funciona está em Deep links adiados no Android.

Outras chamadas

Como ele se comporta

• Primeira abertura: lê o referrer de instalação do Play, registra a instalação e depois entrega o deep link, se houver um.
• Eventos automáticos: first_open, session_start (na abertura, ou após 30 minutos em segundo plano) e app_background. Eles são grátis.
• Os eventos são guardados no dispositivo (até 1.000) e enviados em lotes a cada 15 segundos enquanto o app está aberto, e quando ele vai para segundo plano. Sem conexão, eles esperam e tentam de novo.
• Ele nunca bloqueia, nunca lança exceções e nunca usa o Advertising ID.

Dispositivos de teste

Builds depuráveis são dispositivos de teste automaticamente. Os dados delas são reais, mas ficam ocultos até você ativar Incluir dispositivos de teste em Funil e Jornadas. Mais em Testes.

Privacidade

• Um ID de instalação aleatório, guardado apenas no armazenamento do próprio app. Uma reinstalação recebe um novo.
• Versão do app, versão do sistema, versão do SDK, celular ou tablet, idioma. O país vem da borda da rede. Endereços IP nunca são guardados.
• Sem Advertising ID, sem fingerprinting.
• Nunca coloque nomes, e-mails ou outros dados pessoais nas propriedades dos eventos.

Solução de problemas

• Nada no painel? Ative Incluir dispositivos de teste: builds de depuração ficam ocultas por padrão.
• Ainda nada? Configure com UnolinkOptions(logLevel = LogLevel.DEBUG) e filtre o Logcat por Unolink. Uma chave errada ou revogada aparece no log como erro.
• Sem deep link? Ele só chega em instalações feitas pelo Google Play a partir de um link do Unolink com deep link definido, na primeira abertura. Reinstale para testar de novo, ou use debugInstallReferrer.

Mais em Solução de problemas.