Iniciar sesión Empezar

Emitir entradas personalizadas del registro de actividad

Esta guía explica cómo añadir tus propias entradas personalizadas al registro de Jetpack Activity desde el código de tu plugin o sitio.

Las entradas del registro de Jetpack Activity creadas con esta API aparecen junto a otros eventos, como la publicación de entradas o la actualización de plugins. Esto resulta útil si quieres mostrar eventos relevantes a los administradores del sitio sin crear tu propia interfaz de registro de actividad o auditoría. Esta guía está dirigida a desarrolladores e implica escribir código personalizado.

Requisitos

  • Plugin Jetpack en su versión 15.9 o superior, o
  • Paquete Sync de Jetpack en su versión 4.38 o superior (si tu plugin requiere Sync directamente).
  • El tipo de entrada personalizado denominado jp_act_log_event se registra automáticamente cuando se carga Sync. No necesitas registrarlo por tu cuenta.
  • La persona que realiza la llamada debe tener la capacidad manage_options (normalmente, la de administrador del sitio).

Cómo añadir una entrada al registro de actividad

Puedes crear entradas personalizadas en el registro de actividad de tres formas principales:

  • Desde PHP mediante la clase auxiliar (recomendado).
  • Desde un cliente REST.
  • Directamente mediante wp_insert_post().

Añadir una entrada desde PHP (recomendado)

Utiliza la clase auxiliar denominada Activity_Log_Event para validar y crear entradas.

use Automattic\Jetpack\Sync\Activity_Log_Event;

  $post_id = Activity_Log_Event::create( array(
      'title'    => 'Membership sync failed',
      'content'  => 'Remote API returned 401. Retry queued.',
      'source'   => 'my-plugin',
      'severity' => 'error',
  ) );

  if ( false === $post_id ) {

      // Validation failed (missing/invalid title or content, bad severity).

  }

Si la operación tiene éxito, create() devuelve el jp_act_log_event ID de entrada.
Si falla la validación, devuelve false.

Usar la clase auxiliar es el enfoque recomendado, porque gestiona la validación y garantiza un formato de datos coherente para las entradas del registro de actividad.

Añadir una entrada desde un cliente REST

También puedes crear entradas mediante la WordPress REST API.

Endpoint

POST /wp-json/wp/v2/activity-log-events
Content-Type: application/json
Authorization: OAuth token with admin scope

Cuerpo de la solicitud

{
  "title": "Membership sync failed",
  "content": "Remote API returned 401. Retry queued.",
  "source": "my-plugin",
  "severity": "error"
}

La persona autenticada debe tener la capacidad manage_options. La entrada resultante del registro de actividad tendrá a esa persona como actor.

Añadir una entrada mediante wp_insert_post()

También puedes crear eventos directamente como publicaciones de tipo jp_act_log_event. El campo post_content debe contener una carga útil codificada en JSON con las mismas propiedades que se utilizan en otros lugares.

wp_insert_post(
    array(
        'post_type'   => 'jp_act_log_event',
        'post_status' => 'publish',
        'post_title'  => 'Cache flushed',
        'post_content'=> wp_json_encode(
            array(
                'title'    => 'Cache flushed',
                'content'  => 'Manual cache flush during incident response.',
                'source'   => 'my-snippet',
                'severity' => 'info',
            )
        ),
    )
);

Tú eres responsable de validar estos valores cuando utilices wp_insert_post(). Para evitar entradas no válidas, utiliza preferiblemente la clase auxiliar Activity_Log_Event siempre que sea posible.

Definiciones de los campos

Cada evento del registro de actividad admite las siguientes propiedades:

  • título
    • Tipo: cadena
    • Longitud máxima: 200 caracteres
    • Solo texto sin formato
    • Obligatorio
  • contenido
    • Tipo: cadena
    • Longitud máxima: 5.000 caracteres
    • Solo texto sin formato
    • Obligatorio
  • origen
    • Tipo: cadena
    • Longitud máxima: 100 caracteres
    • Identificador de la herramienta de origen (por ejemplo, my-plugin).
    • Valor predeterminado: Custom entry
    • Opcional
  • gravedad
    • Tipo: enumeración
    • Valores permitidos: info, success, warning, error
    • Valor predeterminado: info
    • Opcional

Lo que ven los propietarios del sitio

Las entradas personalizadas aparecen en el registro de actividad del sitio como eventos normales, identificados como eventos personalizados. En el registro de actividad:

  • El título se utiliza como encabezado del evento.
  • El actor es el usuario de WordPress que realizó la llamada a API (por ejemplo, mediante PHP o REST).

Limitaciones y comportamiento

Las entradas personalizadas del registro de actividad creadas con esta API tienen el siguiente comportamiento:

  • No se pueden editar
    Entradas de escritura única. El jp_act_log_event tipo de entrada personalizado deniega todas las capacidades de edit_* y delete_*.
  • No se publican automáticamente
    Las entradas no se compartirán mediante Jetpack Social, aunque un plugin de terceros añada compatibilidad con Publicize para el tipo de entrada personalizado.
  • No se incluyen en los sitemaps
    El jp_act_log_event tipo de entrada está excluido explícitamente de los sitemaps de Jetpack.
  • Privado en la interfaz pública
    El tipo de entrada utiliza:
    • public => false
    • publicly_queryable => false
    • exclude_from_search => true
    Esto mantiene las entradas fuera de las consultas y búsquedas de la interfaz pública, a la vez que permite que el registro de actividad acceda a ellas y las muestre.

Was this article helpful?