Skip to content
App

Todos los artículos

App Activity API v1

Emperor obtiene usuarios registrados y actividad diaria de las aplicaciones con un contrato compartido. Cualquier aplicación puede implementarlo, no solo las propias. La aplicación queda como origen; las sincronizaciones posteriores actualizan los datos. La misma persona en varias apps no crea un Person duplicado.

Esta página es para equipos que implementan el contrato. El documento OpenAPI 3.1 está en la especificación de App Activity API.

v1 es un borrador y puede cambiar hasta que Emperor lo finalice. Después de la finalización, los cambios incompatibles salen como /v2.

Recursos

La aplicación sirve tres recursos GET bajo /v1, relativos a la URL de App Activity API:

  • /v1/manifest — versión del contrato (1), nombre de la aplicación, zona horaria IANA para agrupar días de actividad y el catálogo de claves de actividad con etiquetas.
  • /v1/users — usuarios. Consulta: updatedSince, cursor, limit.
  • /v1/activity — agregados diarios, una fila por usuario, día y clave del catálogo. Los mismos parámetros de consulta que users.

Si contractVersion no es 1, Emperor rechaza la conexión con un error explícito.

Cursores y sobrescritura de actividad

updatedSince es un datetime ISO-8601 con desplazamiento o Z. Devuelva registros con updatedAt mayor o igual que ese valor. Sin el parámetro, exportación completa. cursor es una cadena opaca del nextCursor de la página anterior. limit vale 100 por defecto y no debe superar 100.

Las listas responden { "data": [...], "nextCursor": null | string }. nextCursor es null en la última página.

Una fila de actividad posterior para el mismo (externalUserId, day, metricKey) sustituye el recuento guardado. Las aplicaciones envían totales diarios, no eventos crudos.

Correo o teléfono

Cada usuario debe incluir email, phone (E.164, por ejemplo +79991234567) o ambos. Un registro sin ninguno lo rechaza el contrato. Emperor lo cuenta como rechazado en la sincronización y no crea un Person.

Cómo Emperor relaciona contactos

Una persona en el CRM es Person. El correo y el teléfono son contactos. La identidad de la aplicación vive en un enlace aparte: una persona, varias apps.

  • El correo se normaliza (trim y minúsculas). El teléfono se guarda en E.164.
  • Una identidad ya vinculada (LINKED) actualiza solo el corte de identidad y la actividad. No se renombra el Person.
  • Una identidad descartada no se empareja.
  • Una identidad nueva sin coincidencias crea un Person y contactos de correo / teléfono.
  • Cualquier coincidencia con un Person existente, incluido un conflicto de correo/teléfono o una segunda aplicación con el mismo correo, va a PENDING_REVIEW. No se crea un segundo Person ni hay fusión automática.

Revisar coincidencias

Abra CRM → Coincidencias de aplicaciones. La cola son coincidencias en espera de revisión. Cada fila muestra el corte de perfil de la aplicación, correo y teléfono, Persons candidatos y el motivo (correo, teléfono, ambos o conflicto correo/teléfono).

Compare los datos entrantes con los contactos y las aplicaciones vinculadas de cada candidato y elija una acción:

  • Vincular al candidato seleccionado. El correo y el teléfono faltantes se añaden como contactos. La identidad queda LINKED. No se crea un segundo Person ni se cambia el nombre.
  • Crear un Person nuevo, igual que una sincronización sin coincidencias. La identidad queda LINKED.
  • Descartar. La identidad queda DISCARDED. La siguiente sincronización no la vuelve a poner en la cola. Emperor registra quién decidió y cuándo.

Lista de conexión

  1. Publicar /v1/manifest, /v1/users y /v1/activity solo por HTTPS en producción.
  2. Emitir un token Bearer de alta entropía por par proyecto–aplicación, solo lectura de esta API. No reutilizar una clave de servicio.
  3. Comparar el token en tiempo constante. Una petición sin Bearer válido responde 401 como RFC 7807 application/problem+json. No distinguir si faltaba el token o era incorrecto.
  4. Aceptar User-Agent: Emperor-AppProvider/1.0 y X-Request-Id (UUID). Devolver ese id en documentos problem al responder errores.
  5. En 429, enviar Retry-After.
  6. Rotación: aceptar el token actual y el anterior durante la ventana de rotación; después revocar el antiguo.

Conectar una aplicación en Emperor

En un proyecto de Development abra Aplicaciones (acción rápida o ajustes del proyecto). Vincule una publicación con conexión App Activity API o cree una publicación nueva (nombre, UID, dominio, servidor, URL de App Activity API, token). El token es solo de escritura: la IU muestra después únicamente la huella.

En las pantallas de edición y vista de la publicación, Actividad de la aplicación guarda esa URL y el token. La vista muestra la URL completa (no «Configurada») y la huella del token.

Comprobar llama a GET {baseUrl}/v1/manifest. Sincronizar en la fila o Sincronizar todas descarga users y después activity en la misma petición HTTP (como máximo cinco minutos). Desvincular borra el vínculo con el proyecto y los cursores; la publicación permanece.

Emperor guarda la conexión, los cursores de sincronización y el historial de ejecuciones. La misma sincronización empareja identidades: sin coincidencia se crea un Person; cualquier coincidencia existente va a revisión.

En la ficha Person, Aplicaciones lista identidades vinculadas, fechas de registro y última visita, y actividad del periodo y métrica elegidos. La lista de contactos del CRM puede filtrar personas con una identidad vinculada de una aplicación.

Límites

  • Una petición de sincronización de más de cinco minutos se detiene.
  • Si la sincronización se queda en curso y responde HTTP 409, Quitar bloqueo en la fila Aplicaciones termina la ejecución como FAILED sin mover cursores. Después vuelva a Sincronizar.
  • La actividad de un usuario rechazado por no tener correo ni teléfono no vuelve tras corregir el perfil hasta que cambie el updatedAt de esa fila de actividad. Una reexportación completa exige desvincular y volver a vincular la aplicación.

Seguridad y registro de auditoría de la aplicación

v1 es HTTPS más un token Bearer en el par proyecto–aplicación.

Recomendado: registrar cada petición de App Activity API con hora, IP de origen, X-Request-Id, User-Agent, recurso (manifest / users / activity), updatedSince, estado HTTP y número de registros devueltos. No registrar el token, la cabecera Authorization, el correo, el teléfono ni los cuerpos de respuesta.

También: un token solo para esta API; límite de ritmo; alertas ante un ráfaga de 401, un User-Agent ajeno, una IP inesperada o un salto brusco de volumen. No exigir una allowlist de IP: las direcciones de salida de Emperor no se reducen a una sola IP fija.

Artículos