Hogar/Documentos/Métricas personalizadas

Contrato de métricas personalizadas

Versión del contrato 2.0.0 · carga útil esquema_versión 2.0

Las métricas personalizadas permiten que el propio servicio de su extensión impulse los números importantes para ello (conversiones, ingresos, estado del backend, embudos) en el mismo panel que ya rastrea las instalaciones y el estado de la tienda web Chrome. el contrato es Basado en metadatos y de doble superficie: cada métrica declara dónde y cómo. aparece tanto en el tablero como en el estado Telegram, por lo que el panel permanece un renderizador genérico sin código específico del producto.

↓ Descargar OpenAPI 3.1 (YAML) /métricas-personalizadas-openapi.yaml · info.versión 2.0.0

1. Cómo funciona (doble superficie)

Su servicio expone un punto final de métricas. Ext Ops Panel es el cliente: tira ese punto final (nunca al revés) y representa el respuesta. La respuesta impulsa dos superficies a la vez:

Pestañas del panel en la extensión Vista detallada: pestañas, secciones y tipos de renderizado por métrica.
Estado Telegram: líneas lógicas compuestas a partir de las mismas métricas, filtradas y formateadas por métrica.

El panel fusiona sus métricas con las métricas base propias (instala/desinstala/reinstala/comentarios/Chrome Web Store/salud), que viven en el reservado base pestaña y línea Telegram.

2. El punto final y la autenticación.

El panel llama a su terminal con GET y espera la v2 carga útil como respuesta 200. Dos modos de extracción comparten la misma forma:

Bajo demanda: se activa cuando un usuario abre Detalles. Tarifa limitada a como máximo 1 solicitud por minuto por fuente, en todos los planes, incluido Gratis.
Escucha: según un cronograma (solo de prueba/pago), compone el estado Telegram y las alertas de borde.

La autenticación es una de ninguno, portador o encabezado_clave_api. Los secretos se almacenan cifrados en reposo en el backend del panel y nunca se entregan. a la extensión del tablero. Si falla un tirón, el panel se degrada con gracia (última instantánea u oculta) sin romper las métricas base.

3. Estructura de carga útil

La carga útil de nivel superior lleva el diseño (pestañas, secciones, Telegram líneas) y la matriz de métricas.

Campo	Tipo	Notas
`schema_version`	cadena	Requerido. Debe ser `"2.0"`.
`generated_at`	cadena (fecha-hora)	Cuándo se compuso la carga útil (frescura/detección de inactividad).
`tabs`	Pestaña[]	Pestañas del tablero. Ver sección 4.
`sections`	Sección[]	Grupos de métricas dentro de una pestaña (`tab`, `id`, `title`, `order`).
`telegram`	TelegramMeta	Plantilla `header` + `lines[]`. Ver sección 7.
`metrics`	Métrico[]	Las métricas mismas. Ver secciones 5 y 6.

4. Pestañas e íconos de pestañas

Una pestaña es { id, title, order, icon? }. el reservado base La pestaña es propia del panel. (icon="layout-dashboard"); tu servicio suma el resto. cuando muchos Las pestañas están abiertas, la pestaña activa muestra el icono + título y las demás colapsan en la solo ícono (el título permanece en la información sobre herramientas y en la etiqueta aria).

El valor icon es una de dos cosas:

A Nombre del icono de Lucide en kebab-case ASCII (coincide ^[a-z][a-z0-9-]*$), p.e. trending-up. Un bien formado pero El nombre no admitido se degrada al icono predeterminado (square) para que la barra nunca se rompa.
A emoji único, p.ej. 💰 o 🚀, representado como texto.

El panel envía un subconjunto seleccionado de 37 nombres de Lucide (mantenidos reducidos para el paquete MV3):

panel de diseño
actividad
indicador
capas
enchufar
signo de dolar
billete de banco
billetera
tarjeta de crédito
recibo
gráfico de barras-3
gráfico de líneas
gráfico circular
tendencia al alza
tendencia a la baja
usuarios
usuario
triángulo de alerta
campana
reloj
rama git
paquete
caja
base de datos
servidor
UPC
borrar
globo
rompecabezas
embudo
filtrar
cuadrado
círculo
picadillo
por ciento
etiqueta
bandera

5. Métrica: valor + dos bloques de ubicación

Una métrica lleva un valor escrito más dos bloques independientes: dashboard (dónde y cómo en la extensión) y telegram (dónde y cómo en el mensaje). Se puede omitir o oculto a través de show:false, por lo que una métrica puede residir solo en una superficie.

Campo	Notas
`id`	Identificación de métrica estable, única en la carga útil.
`kind`	Tipo de datos (apartado 5.1). Selecciona qué campos de valor se aplican.
`label`	Etiqueta humana canónica.
`value` y campos tipo	Los campos de carga útil dependen de `kind` (sección 5.1).
`severity`	Uno de `ok`, `info`, `warn`, `crit` (mapas a color/emoji).
`shareable`	Booleano opcional, predeterminado `true`. Cuando `false` la métrica es solo del propietario: en un proyecto compartido de solo lectura, se elimina del lado del servidor y nunca llega a una vista pública/de observador (uso para métricas financieras). Gobierna el acceso, no la ubicación.
`dashboard`	`{ show, tab, section, order, name, render, options }` (sección 5.2).
`telegram`	`{ show, line, pos, format, sep, when }` (apartados 6 y 8).

5.1. Tipos (tipo de datos + carga útil)

Los tipos son un conjunto abierto: el renderizador ignora un tipo desconocido (compatible con versiones posteriores).

amable	Campos de carga útil	Uso de ejemplo
`number`	`value` (+ opcional `delta`, `unit`)	instalación/retroalimentación cuenta
`delta`	`value`, `delta` (representa `1200 (+72)`)	total (+hoy)
`percent`	`value` (0 a 100)	tasa de éxito del motor
`duration`	`seconds` o `minutes`	p50/p95/avg, frescura
`bytes`	`bytes` o `kb`	tamaño de salida (~522 KB)
`rating`	`value`, `count`	5.0★ (1)
`money`	`value`, `currency`, opcional `delta`	MRR, gastar
`status`	__CODEBLOQUE_63__ + __CODEBLOQUE_64__	semáforo de salud
`series`	`points:[{date,count}]`, multiopcional `series:[{name,points}]`	instalaciones diarias, usuarios activos
`intraday`	`series:[{name,intraday:[{minute,value}]}]`, opcional `step_min` (predeterminado 15), `tz`	hoy por cubos de 15 minutos
`hour_histogram`	`{ weekdays:[...], start, end, tz }`	conversiones por hora
`funnel`	`steps:[{key,label,value}]`	precios para pagar
`breakdown`	`items:[{label,value,unit?,sub?/money?}]`	submarinos por plano, por motor, por superficie
`list`	`items:[{text,count?,severity?}]`	errores recientes
`text`	`value` (cadena)	texto libre

5.2. Render (cómo mostrar en el tablero)

dashboard.render elige el objeto visual (normalmente coincide con kind, pero puede diferir, p.e. mostrar un percent como badge). también un conjunto abierto.

prestar	Mirar	Opciones (`dashboard.options`)
`kpi`	Tarjeta: nombre + valor grande + delta	`tone`
`badge`	Píldora de estado/pictograma por gravedad	–
`chart`	Gráfico de líneas (mes/vida útil, promedio móvil de 7, desplazamiento)	`series`, `defaultMode`
`intraday`	Hoy por cubos (96 por UTC día): barras apiladas o líneas suavizadas, eje de tiempo `HH:MM`, lectura al pasar el cursor sobre las series	`mode` (`bars` \| `lines`, predeterminado `lines`)
`hour_histogram`	Barras horarias, agrupadas entre semana/fin de semana/por día de la semana	`series`
`funnel`	Pasos con conversión entre ellos.	–
`breakdown`	Barras categóricas horizontales con valor + participación del total	`items`
`table`	Tabla (por ejemplo, comentarios)	`columns`
`text`	Párrafo / en línea	–
`status`	Estado del semáforo por gravedad	–
`list`	Lista de elementos con recuento/gravedad opcional	–

intraday frente a chart. El chart el eje es a diario (points[].date = YYYY-MM-DD) y su La vista mensual se divide en los últimos 30 puntos, por lo que los 96 segmentos de hoy no caben en ella. intraday es el gráfico Hoy propio expuesto como tipo de contrato: el misma convención donde minute cuenta los minutos desde el inicio del día UTC (0, 15,…, 1425), pero las series y datos están declarados por la fuente. Enviar solo cubetas no vacías, el panel densifica el resto.

Un depósito vacío es null, no 0. para un promedio (por ejemplo, tiempo medio de conversión) un cero sería una mentira, por lo que la línea se rompe en lugar de caer al suelo. Falta un depósito y value: null son equivalente: la línea se rompe, no se dibuja ninguna barra y la lectura al pasar el mouse muestra un guión.

6. El panel es dueño de la paleta.

Se asignan colores de gráficos y series. por el panel de la marca tokens, no por la fuente. options.series[] solo lleva identidad ({key,label,order}); un campo color en la carga útil es asesoramiento y ignorado. Las claves semánticas se asignan a tokens fijos (paid para acentuar, free para silenciar neutral, failed/error al peligro, ready/success hasta el éxito); otras llaves toman el paleta de marcas categóricas posicionalmente. El contraste se mantiene al menos en 4,5:1 en ambos temas. Esto protege la marca de maleficios externos arbitrarios.

7. Plantillas Telegram

telegram.header es el encabezado del mensaje; telegram.lines[] son líneas lógicas ({ id, order, prefix, when }). El compositor recoge cada métrica con un telegram.line dado, filtra por when, ordena por pos, representa cada uno a través de su plantilla format y une ellos con el sep de cada métrica. Se imprime la línea prefix primero. Todo es texto plano.

Marcador de posición	Producción
`{value}`	Por tipo (número `1,200`; porcentaje `99%`)
`{value:k}`	`1.2k` / `3.0M` (compacto)
`{delta:+}`	`+72` / `-3`
`{value:pct}`	`99%`
`{seconds:dur}`	`28s` / `5m 47s`
`{minutes:age}`	`45m` / `2h 30m` / `never`
`{bytes:size}`	`~522KB` / `1.4MB`
`{value}★ ({count})`	`5.0★ (1)`
`{sev}`	Emoji de gravedad: 🟢 ok, 🟡 advertir, 🔴 crítico, ⚪ inactivo
`{trend}`	`↗` / `↘` (±5pp vs 7d)

8. Condiciones de visibilidad (cuándo)

when controla si un campo de métrica (o una línea completa Telegram) muestra. Valores:

cuando	Muestra el campo
`always`	Siempre (predeterminado).
`nonzero`	Sólo cuando el valor no es 0/vacío.
`severity>=warn`	Sólo cuando la severidad es advertencia o crítico.
`changed`	Solo cuando cambió desde la instantánea anterior.

Los valores when desconocidos se comportan como always (compatible con versiones posteriores).

9. Ejemplo de carga útil

{
  "schema_version": "2.0",
  "generated_at": "2026-07-02T23:17:30Z",
  "tabs": [
    { "id": "conv", "title": "Conversions", "order": 1, "icon": "trending-up" }
  ],
  "sections": [
    { "tab": "conv", "id": "by_hour", "title": "By hour", "order": 0 }
  ],
  "telegram": {
    "header": "{name} • {cws.users} • {cws.rating}★ ({cws.rating_count})",
    "lines": [
      { "id": "base", "order": 0 },
      { "id": "conv", "order": 1, "prefix": "{sev} Conv " }
    ]
  },
  "metrics": [
    {
      "id": "conv_today",
      "kind": "number",
      "label": "Conversions today",
      "value": 254,
      "severity": "ok",
      "shareable": true,
      "dashboard": {
        "show": true,
        "tab": "conv", "section": "by_hour", "order": 10,
        "name": "Today", "render": "kpi", "options": {}
      },
      "telegram": {
        "show": true,
        "line": "conv", "pos": 20,
        "format": "today {value}", "sep": " • ", "when": "always"
      }
    }
  ]
}

Solo se admite la versión 2 nativa. Su servicio devuelve métricas más un diseño listo según este contrato; no hay conectores de formato heredado. tipos y los tipos de renderizado provienen de los conjuntos declarados anteriormente; los desconocidos son ignorados por lo que una fuente más nueva nunca rompe un panel más antiguo.

10. El contrato legible por máquina

La descripción formal e importable de este punto final es el archivo OpenAPI 3.1. Lleva la misma versión de contrato (2.0.0) y es el único canónico artefacto de máquina, compartido entre idiomas.

↓ Descargar OpenAPI 3.1 (YAML) /métricas-personalizadas-openapi.yaml