El objeto state
Todos los campos que controlan lo que muestra la tarjeta en el celular.
state es lo que muestra la tarjeta. Qué diseño muestra cada campo está en diseños. Las reglas:
- En una actualización (y en el
finalStatede un fin), los campos enviados se combinan con el estado guardado. Los campos no enviados conservan su valor. versusse combina igual, un nivel más abajo.segmentsse reemplaza completo.- Para borrar un campo, envíalo como
""(o[]parasegments). - Todo el estado debe pesar 16KB o menos.
Android dibuja una notificación del sistema a partir del texto, el color de acento, el ícono, la foto de Imagen, la barra de progreso, las puntuaciones, el logo de la liga y el botón de acción. Los campos marcados como solo iPhone no hacen nada en Android.
Diseño y texto
| Campo | Tipo | Predeterminado | Instrucciones |
|---|---|---|---|
layout | string | progress | progress, picture, versus o countdown. Defínelo al iniciar. Cámbialo en una actualización para cambiar el tipo. |
primaryText | string | "" | El titular en Progreso, el pie de foto en Imagen. También es el título de cada alerta, así que defínelo en todos los diseños. |
secondaryText | string | "" | La línea bajo el titular, y el cuerpo de cada alerta. En Cuenta regresiva, el nombre junto al reloj. |
stage | string | ninguno | Una palabra corta para el paso actual (“En camino”). iPhone la muestra en la Dynamic Island compacta, solo en Progreso. Android 16 la muestra en el chip de estado. Mantenla cerca de 7 caracteres. |
isComplete | boolean | false | true para el estado final. Progreso muestra “Listo” en la Dynamic Island compacta. La tarjeta se queda hasta que se finaliza. |
Colores
Los colores son texto #RRGGBB. No hay campo de color de texto: el texto se vuelve negro o blanco para que se lea bien. La Dynamic Island siempre es oscura.
| Campo | Tipo | Predeterminado | Instrucciones |
|---|---|---|---|
accentColorHex | string | azul | El color de la marca: la barra de progreso, los matices y el acento de Android. Sobre un color de fondo personalizado, la barra es negra o blanca. brand.color lo define cuando el estado no lo hace. |
backgroundColorHex | string | negro | El fondo de la pantalla bloqueada (Progreso, Versus, Cuenta regresiva). Solo iPhone. |
backgroundGradientHex | string | ninguno | Un segundo color. Con backgroundColorHex, el fondo pasa a ser un degradado (Progreso, Versus, Cuenta regresiva). Solo iPhone. |
Imágenes
Los campos de imagen aceptan una URL https completa que el celular pueda descargar. Usa WebP. Las formas y los tamaños están en imágenes que encajan. Una URL de imagen nueva en una actualización reinicia la tarjeta, así que mantén las mismas URL entre llamadas.
| Campo | Tipo | Predeterminado | Instrucciones |
|---|---|---|---|
headerIconUrl | string | ninguno | El logo en Progreso y Cuenta regresiva, y la marca pequeña en Imagen. Se dibuja como un cuadrado redondeado. |
backgroundImageUrl | string | ninguno | Una imagen de tamaño completo detrás de la tarjeta: la foto de Imagen, o el fondo de Progreso o Versus. Una capa oscura mantiene el texto legible. Cuenta regresiva no la muestra. |
lockScreenImageUrl | string | ninguno | Una versión para la pantalla bloqueada de headerIconUrl, cuando la pantalla bloqueada necesita una imagen distinta a la de la Dynamic Island oscura. La usan Progreso e Imagen. |
islandImageUrl | string | ninguno | Solo Imagen. Una foto aparte para la Dynamic Island, que es más pequeña que la pantalla bloqueada. Si falta, usa la foto de la pantalla bloqueada. Solo iPhone. |
androidIconUrl | string | ninguno | Reemplaza headerIconUrl en Android. |
androidImageUrl | string | ninguno | Reemplaza backgroundImageUrl en Android. Imagen la muestra como la foto expandida. |
immersive | boolean | false | true quita la capa oscura sobre backgroundImageUrl. Úsalo solo con imágenes oscuras. Solo iPhone. |
Progreso
| Campo | Tipo | Predeterminado | Instrucciones |
|---|---|---|---|
progress | number | 0 | Relleno de la barra de 0 a 1. Con segments en el estilo segmentado, se usa en su lugar la proporción de pasos completados. |
progressStyle | string | segmented | segmented (una cápsula por paso) o linear (una barra, con sus extremos rotulados con las etiquetas del primer y del último paso). |
segments | object[] | ninguno | Los pasos, cada uno { "label": string, "complete": boolean }. Hasta 12. Envía la lista completa en cada actualización. |
estimatedMinutes | number | ninguno | Minutos enteros. Muestra “N min” en la Dynamic Island compacta cuando no hay stage. 0 lo oculta. Solo iPhone. |
Cuenta regresiva
| Campo | Tipo | Predeterminado | Instrucciones |
|---|---|---|---|
countdownTo | number | ninguno | La hora objetivo en segundos de época Unix, como número (no milisegundos ni texto). El reloj corre en el celular. Se envía una alerta cuando llega la hora. |
countdownStyle | string | auto | hms (00:00:00), days, hours, months, years o auto. auto muestra un reloj en marcha (00:00:00) en las últimas 36 horas, y antes de eso la unidad entera más grande. |
completionText | string | ninguno | Se muestra en lugar del reloj cuando llega la hora, y es el título de esa alerta. Sin él, iPhone muestra secondaryText y Android muestra primaryText. |
Botón de acción
Para quitar el botón, envía los tres campos como "".
| Campo | Tipo | Predeterminado | Instrucciones |
|---|---|---|---|
actionLabel | string | ninguno | El texto del botón (“Ver en vivo”). iPhone lo muestra en Imagen y Versus, en la pantalla bloqueada y en la Dynamic Island expandida, no en la compacta. Android lo muestra en cualquier diseño cuando actionURL está definido. |
actionURL | string | ninguno | La URL http o https que abre el botón. Las demás URL se descartan. |
actionColorHex | string | rojo (Versus), naranja (Imagen) | El color del botón. Solo iPhone. |
El objeto versus
Defínelo dentro de state cuando layout es versus.
| Campo | Tipo | Predeterminado | Instrucciones |
|---|---|---|---|
leftName / rightName | string | "" | Los nombres de los dos lados. |
leftScore / rightScore | string | "0" | Puntuaciones como texto, así que “12”, “$1,500” y “X” funcionan. Los números se convierten en texto. |
leftStatus / rightStatus | string | "" | Una línea pequeña bajo cada nombre (“Ganador”). |
activeSide | string | ninguno | "left" o "right". Cuando la Dynamic Island está en su tamaño mínimo, muestra el logo de ese lado. |
leftColorHex / rightColorHex | string | color de texto | El color de la puntuación de cada lado. Solo iPhone. |
centerLabel | string | ninguno | Texto pequeño en el centro (“Mapa”). |
centerValue | string | ninguno | El valor debajo (“Overpass”). |
leftImageUrl / rightImageUrl | string | ninguno | Los dos logos. Los PNG transparentes se ven mejor. |
centerImageUrl | string | ninguno | Una imagen en el centro (un artículo de subasta, un mapa). |
sourceLogoUrl | string | ninguno | El logo de la liga o la marca: la franja inferior en iPhone, el mosaico del Apple Watch y el ícono de Android. |
El objeto brand
Opcional, se define en el nivel superior de la llamada start. Cámbialo después con POST /api/branding. El sitio que se muestra bajo el nombre de la marca viene de la página que aloja el botón de lanzamiento, así que no es un campo de marca.
| Campo | Tipo | Instrucciones |
|---|---|---|
title | string | El nombre de la actividad en la lista de la app. Si falta, usa name. |
name | string | El nombre de la marca (“Acme”). Se muestra en la app, en la franja inferior de Versus y como título de la alerta cuando primaryText está vacío. Omítelo para no mostrar nombre de origen. |
logo | string | La URL del logo para la portada de la app. Si falta, usa headerIconUrl y luego el logo de WebActivity. |
description | string | Una línea corta bajo el título en la portada. Si falta, usa secondaryText. |
color | string | El color de la marca como #RRGGBB. Define accentColorHex cuando el estado no lo tiene. |
