SDK de Android

Kotlin, utilizable desde Java. El SDK solo depende de la biblioteca Play Install Referrer de Google y de lifecycle-process de AndroidX. Plan Pro y superiores.

Requisitos

• Android 6.0+ (minSdk 23).
• Kotlin o Java.
• Una clave del SDK: en el panel, abre tu app → Ajustes → Claves del SDK → Nueva clave. Solo se muestra una vez, así que cópiala en ese momento.

Instalación

El SDK está en Maven Central, que ya usa todo proyecto nuevo de Android. Añade una línea al módulo de la app y sincroniza Gradle:

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

Configuración

Llama a configure una vez, en tu clase Application, antes de que se ejecute cualquier otra cosa:

import dev.unolink.Unolink

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

¿Aún no tienes clase Application? Crea esta y regístrala en AndroidManifest.xml:

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

Java:

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

Opciones

Pasa UnolinkOptions como tercer argumento. Todos los campos son opcionales.

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

La clave es pública: va dentro de tu app y solo puede enviar datos de esa app. Consulta Claves del SDK.

Eventos del embudo

Añade una línea en cada momento importante. Se convierten en los pasos de Embudo y Recorridos.

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

Sin RevenueCat, informa tú de las pruebas y compras. El importe es un BigDecimal, así que los precios nunca se redondean:

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

Tus propios eventos aceptan un nombre y hasta 20 propiedades:

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

La lista completa, con los nombres que llegan al panel, está en Eventos.

ID de usuario y RevenueCat

Si usas RevenueCat, conéctalo en tu app → Ajustes → RevenueCat. Después, no llames a purchase ni a trialStarted: RevenueCat envía él mismo las pruebas, compras, renovaciones, cancelaciones y reembolsos, y Unolink ignora las llamadas de compra de la app para que nada cuente dos veces.

Para unir esas compras a la instalación, informa del propio ID de usuario de app de RevenueCat. Con el SDK 0.3.2 o posterior, una línea lo mantiene al día. Llámala una vez al iniciar, antes o después de configure:

Unolink.connectRevenueCat { Purchases.sharedInstance.appUserID }

Unolink lee el ID al iniciar, cada vez que la app pasa al primer plano y antes de cada evento, y solo lo envía cuando ha cambiado. Si RevenueCat aún no está configurado, la lectura falla sin hacer ruido y se vuelve a intentar más tarde. Después de Purchases.sharedInstance.logIn y logOut, llama a Unolink.revenueCatUserChanged() para enviar el nuevo ID de inmediato.

Sin ella (o antes de la 0.3.2), llama a setUserId con el ID de RevenueCat después de Purchases.configure, después de cada Purchases.logIn y Purchases.logOut, y en cada inicio. Usa uno u otro, no los dos:

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

Para un invitado, eso es el ID anónimo de RevenueCat, así que una compra hecha antes de registrarse se une a la instalación de inmediato. Después de logIn, es el ID de la cuenta. Cuenta cada ID que haya informado una instalación, así que la compra del invitado se mantiene unida. Consulta Invitados y cuentas.

Unolink nunca guarda el ID en sí, solo un hash unidireccional distinto para cada una de tus apps.

Deep links diferidos

Cuando alguien toca un enlace de Unolink en Android, instala desde Google Play y abre la app, el SDK lee el referrer de instalación de Play y llama a tu listener una vez, en el hilo principal. Configura el Enlace profundo y los Parámetros del enlace en el panel (Enlaces → ⋯ → 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()
}

El listener se llama una vez por instalación. Regístralo justo después de configure, o más tarde: un enlace que llegó antes de que lo registraras se entrega igualmente, también en un inicio posterior si antes no había ningún listener.

Ábrelo después del onboarding

Las primeras aperturas suelen empezar en el onboarding. Si la pantalla del enlace está detrás del onboarding o del inicio de sesión, no lo abras desde el listener. Cuando termine el onboarding (o el inicio de sesión), lee el enlace pendiente, ábrelo y luego márcalo 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()
}

El enlace espera hasta que lo consumas, aunque la app se cierre entretanto (hasta 30 días después de la instalación; 0.3.3+). Un usuario nuevo que abandona a mitad del onboarding lo recibe igualmente en el siguiente inicio, así que no necesitas guardarlo tú. Llama a consumeDeferredDeepLink() en cuanto lo hayas abierto: hasta entonces, getPendingDeferredDeepLink() lo devuelve en cada inicio. Es null antes de configure y hasta que Google Play responde (un segundo o dos en el primer inicio).

Para probar sin una instalación desde Play, usa debugInstallReferrer (consulta Pruebas). Cómo funciona el referrer está en Deep links diferidos en Android.

Otras llamadas

Cómo se comporta

• Primer arranque: lee el referrer de instalación de Play, registra la instalación y después entrega el deep link si lo hay.
• Eventos automáticos: first_open, session_start (al arrancar, o tras 30 minutos en segundo plano) y app_background. Son gratis.
• Los eventos se guardan en el dispositivo (hasta 1.000) y se envían en lotes cada 15 segundos mientras la app está abierta, y cuando pasa a segundo plano. Sin conexión, esperan y se reintentan.
• Nunca bloquea, nunca lanza excepciones y nunca usa el Advertising ID.

Dispositivos de prueba

Las builds depurables son dispositivos de prueba automáticamente. Sus datos son reales, pero están ocultos hasta que activas Incluir dispositivos de prueba en Embudo y Recorridos. Más en Pruebas.

Privacidad

• Un ID de instalación aleatorio, guardado solo en el almacenamiento propio de tu app. Una reinstalación recibe uno nuevo.
• Versión de la app, versión del sistema operativo, versión del SDK, teléfono o tablet, idioma. El país viene del borde de la red. Las direcciones IP nunca se guardan.
• Sin Advertising ID, sin fingerprinting.
• Nunca pongas nombres, emails ni otros datos personales en las propiedades de los eventos.

Solución de problemas

• ¿No aparece nada en el panel? Activa Incluir dispositivos de prueba: las builds de depuración están ocultas por defecto.
• ¿Sigue sin aparecer nada? Configura con UnolinkOptions(logLevel = LogLevel.DEBUG) y filtra Logcat por Unolink. Una clave incorrecta o revocada se registra como error.
• ¿No llega el deep link? Solo llega en instalaciones desde Google Play a través de un enlace de Unolink con un deep link configurado, en el primer arranque. Reinstala para volver a probar, o usa debugInstallReferrer.

Más en Solución de problemas.