KappS Base de conocimiento · Blog

Google Play Install Referrer API en 2026: datos de atribución y estados de conexión

Blog Guía

La atribución de instalaciones es la única medición de la que depende cada instalación de pago y, en Google Play, proviene de una interfaz única y pequeña: la API de Install Referrer. No es una función del panel ni te envía cifras por correo: entrega a tu app el contenido de referencia que Play registró en el momento de la instalación, una sola vez, y a partir de ahí es tu responsabilidad almacenarlo y conciliarlo. Este tutorial recorre todo el proceso: qué devuelve la API, cómo conectarse, cómo leer la respuesta, la regla de los 90 días que muchos equipos descubren demasiado tarde y qué hacer con cada estado de conexión.

Todo lo que sigue se basa en las páginas de referencia de Google sobre la API Install Referrer y la biblioteca cliente Play Install Referrer, ambas consultadas el 27/10/2026.

Paso 1 — Conoce exactamente qué devuelve la API antes de diseñar en torno a ella

La API recupera el contenido de referidos registrado por la app de Play Store, y la carga útil documentada es limitada y específica:

  • la URL de referencia del paquete instalado;
  • la marca de tiempo, en segundos, del clic del referente: disponible tanto en el cliente como en el servidor;
  • la marca de tiempo, en segundos, de cuándo comenzó la instalación — de nuevo tanto del lado del cliente como del servidor;
  • la versión de la app en el momento de la primera instalación;
  • si el usuario interactuó con la experiencia instantánea de tu app en los últimos 7 días.

Dos requisitos lo condicionan todo. La API la expone la app Play Store en el dispositivo, y los dispositivos con Play Store 8.3.73 o posterior tienen acceso automáticamente. También necesitas una cuenta de Google Play Console. En esencia, la API es una interfaz AIDL; se espera que los desarrolladores de Kotlin y Java usen el contenedor de la biblioteca cliente en lugar del AIDL sin procesar.

Consecuencia de diseño: se trata de atribución de primera instalación con una marca de tiempo del clic y una marca de tiempo del inicio de la instalación. No hay cadena multitáctil, ni view-through, ni grafo entre dispositivos en la respuesta. Si tu modelo de informes asume alguno de estos, los datos tienen que venir de otro sitio.

Paso 2 — Añade la biblioteca cliente

En el build.gradle del módulo de la app, añade la dependencia. La versión documentada en la página de la biblioteca cliente es la 2.2:

dependencies { ... implementation "com.android.installreferrer:installreferrer:2.2" }

Si tu módulo está configurado para Kotlin DSL, la misma coordenada se añade con implementation("com.android.installreferrer:installreferrer:2.2"). No se necesita nada más: ni un receptor en el manifiesto, ni permisos, ni una opción en Play Console. Esta biblioteca es la que sustituye al antiguo enfoque de receptor de difusión; no mantengas ambas rutas.

Paso 3: conéctate a la app Play Store

La conexión es asíncrona, y ese simple hecho es el origen de la mayoría de las implementaciones defectuosas. La secuencia documentada es: crear un cliente con InstallReferrerClient.newBuilder(this).build(), llamar a startConnection() y pasar un InstallReferrerStateListener que reciba el resultado.

referrerClient = InstallReferrerClient.newBuilder(this).build() referrerClient.startConnection(object : InstallReferrerStateListener { override fun onInstallReferrerSetupFinished(responseCode: Int) { when (responseCode) { InstallReferrerResponse.OK -> { /* conexión establecida */ } InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> { /* API no disponible en esta app de Play Store */ } InstallReferrerResponse.SERVICE_UNAVAILABLE -> { /* no se pudo establecer la conexión */ } } } override fun onInstallReferrerServiceDisconnected() { /* vuelve a llamar a startConnection() antes de la siguiente solicitud */ } })

Lee el contrato de devolución de llamada al pie de la letra. OK significa que la conexión se estableció y puedes continuar. FEATURE_NOT_SUPPORTED significa que la API no está disponible en la app de Play Store de ese dispositivo: una versión de la tienda antigua o no estándar, no un error en tu código. SERVICE_UNAVAILABLE significa que la conexión no se pudo establecer en absoluto, lo que es un problema de sincronización, no un veredicto.

La desconexión es lo esperable, no la excepción: la propia nota de Google indica que el cliente puede perder la conexión si el servicio de Play Store se está actualizando en segundo plano, y que el cliente debe llamar de nuevo a startConnection() para reiniciarla antes de hacer más solicitudes. Así que el listener no es de un solo uso; trátalo como una máquina de estados que tú controlas.

Paso 4 — Lee los datos del referente

Una vez conectado, getInstallReferrer() es una llamada sincronizada que devuelve un objeto ReferrerDetails. Los campos se corresponden uno a uno con la carga útil indicada en el paso 1:

val response: ReferrerDetails = referrerClient.installReferrer val referrerUrl: String = response.installReferrer val referrerClickTime: Long = response.referrerClickTimestampSeconds val appInstallTime: Long = response.installBeginTimestampSeconds val instantExperienceLaunched: Boolean = response.googlePlayInstantParam

Dos de estos son más útiles de lo que parecen. referrerClickTimestampSeconds y installBeginTimestampSeconds te permiten calcular el delta entre clic e instalación por campaña: un delta lento suele significar que fue la página de la tienda, y no el anuncio, lo que hizo perder al usuario. googlePlayInstantParam indica si la instalación provino de una experiencia instantánea en los últimos 7 días, la única señal de atribución instantánea en la respuesta.

Paso 5 — Respeta la ventana de 90 días y hazlo una sola vez

Esta es la frase que hace que los equipos pierdan sus datos históricos: la información del referente de instalación estará disponible durante 90 días y no cambiará a menos que se reinstale la aplicación. La indicación de Google que sigue es igual de directa: para evitar llamadas innecesarias a la API, invócala solo una vez durante la primera ejecución tras la instalación.

Los 90 días no son una licencia de almacenamiento. Son la ventana en la que el valor aún se puede recuperar desde Play, así que una app que solo lo lee de forma diferida, en alguna sesión posterior, tiene una fecha límite estricta. Léelo en la primera ejecución tras la instalación y persístelo. Como no cambia salvo que se reinstale la app, un bucle de actualización no te aporta nada y solo añade llamadas.

Cierra la conexión cuando termines: llama a endConnection() en el cliente. El motivo de Google es explícito: cerrar la conexión evita fugas de memoria y problemas de rendimiento en el dispositivo.

Paso 6 — Ramifica según el código de respuesta, no reintentes a ciegas

La lectura de atribución en el primer lanzamiento está en la ruta crítica de la primera experiencia del usuario, así que la política de fallos importa tanto como el código. Una asignación viable:

  • Aceptar: lee, persiste y llama a endConnection(). No vuelvas a leer en lanzamientos posteriores.
  • SERVICE_UNAVAILABLE: trátalo como "ahora no". No guardes nada, no bloquees la primera pantalla y vuelve a intentarlo en un lanzamiento posterior dentro de la ventana de 90 días.
  • FEATURE_NOT_SUPPORTED: la API no está disponible en este dispositivo. Recurre al identificador de campaña que lleve tu propio enlace y registra que la lectura no fue compatible, para que tus informes no la cuenten en silencio como orgánica.
  • Desconectado — reinicia con startConnection() antes de la siguiente solicitud; no des por hecho que el cliente sigue activo.

Hay una regla de ingeniería que está por encima de las otras cuatro: nunca dejes que la atribución bloquee la experiencia del primer arranque y nunca permitas que una lectura fallida escriba una fila de atribución "orgánica" falsa. La diferencia entre "sin datos" y "orgánico" es exactamente donde los informes de instalaciones dejan de cuadrar.

Paso 7 — Trata la cadena de referrer como entrada no confiable

La biblioteca cliente devuelve el valor del referrer como una cadena. Lo entrega la plataforma, pero sigue siendo un valor que se originó fuera de tu app, así que se aplica la higiene habitual para entradas externas: conviértelo en pares clave-valor de forma defensiva, limita su longitud y nunca lo insertes sin validar en una URL, una ruta de enlace profundo o una consulta a la base de datos.

En la práctica, eso significa: decodificar el valor, dividirlo por los separadores documentados, incluir en la lista blanca las claves de campaña que realmente reconozcas y descartar todo lo demás. Después, concílialo con tu propio evento del lado del servidor antes de que se convierta en un dato de facturación o de ingresos. Los datos de atribución deciden qué canal recibe presupuesto: una cadena sin validar no debería poder mover dinero.

Si la cadena de referrer se reenvía a redes publicitarias o a un MMP, comprueba que tu declaración de Seguridad de los datos de Play y tu política de privacidad ya cubren esa compartición antes de que el proceso salga a producción, no después de una auditoría. La infraestructura de atribución es recopilación de datos; la declaración tiene que describirla.

Paso 8 — Anota lo que la API no te dice

La mayoría de las disputas de atribución surgen de esperar algo equivocado de una respuesta correcta. Según las dos páginas de referencia, los límites reales son:

  • Los dispositivos con una versión de Play Store inferior a la 8.3.73 simplemente no tienen la API: planifica la alternativa, porque FEATURE_NOT_SUPPORTED es un resultado real, no un error para registrar y olvidar.
  • El valor se fija en la primera instalación y no cambia salvo que se reinstale la app, así que no puede expresar una reactivación, una actualización ni un toque de campaña posterior.
  • La recuperabilidad termina a los 90 días: todo lo que no guardaste en ese plazo se pierde.
  • El indicador de experiencia instantánea solo abarca una ventana retrospectiva de 7 días.
  • Es una señal a nivel de dispositivo y cuenta para las instalaciones desde Play; no es una identidad de usuario y no eliminará duplicados entre dispositivos.

Incluye esos cinco límites en el mismo documento que tu esquema de atribución. Cuando un informe de campaña y un informe de ingresos no coinciden, la discrepancia suele deberse a una de estas cinco afirmaciones, no a un fallo del cliente.

Fuentes: Android Developers — Google Play Install Referrer API (developer.android.com/google/play/installreferrer): campos del payload, requisito de Play Store 8.3.73+, interfaz AIDL, requisito de cuenta de Play Console. Android Developers — Play Install Referrer Library (developer.android.com/google/play/installreferrer/library, página actualizada por última vez el 2026-10-23): versión de dependencia 2.2, flujo de conexión y códigos de respuesta, campos de getInstallReferrer() y ReferrerDetails, la nota sobre disponibilidad de 90 días, la recomendación de consultar una vez por instalación y endConnection(). Ambas consultadas el 2026-10-27. Google no publica tasas de atribución por campaña ni cifras de latencia del lado de la tienda; aquí no se infiere ninguna.

¿Gestionas cuentas de desarrollador a escala? Nosotros nos encargamos de la parte operativa.

Haz clic para elegir un archivo · clic derecho → Pegar, o pulsa Ctrl/⌘+V para pegar una captura de pantalla

También puedes arrastrar un archivo a este cuadro.

Respondemos al correo que nos proporciones. Tus datos se quedan con KappS.

✔ Enviado

Hemos recibido tu mensaje y responderemos en un plazo de 24 horas.


← Volver a editar