Hooks y Filtros

Esta referencia está dirigida a los desarrolladores que desean extender ReadNinja de forma programática. Todos los hooks y filtros son estables y están disponibles en las versiones Gratuita y Pro.

Filtros PHP

Filtro	Parámetros	Descripción
`rpb_is_pro`	`bool`	Devuelve `true` si la licencia Pro está activa
`rpb_should_display`	`bool $display, int $post_id`	Controla programáticamente si la barra se renderiza
`rpb_bar_config`	`array $config`	Modifica el array de config JS antes de que se imprima en la página
`rpb_settings_tabs`	`array $tabs`	Añade o elimina pestañas en la página de ajustes

`rpb_is_pro`

Permite a otros plugins verificar si Pro está activo sin codificar nombres de clase o constantes.

add_action( 'init', function () {
    if ( apply_filters( 'rpb_is_pro', false ) ) {
        // Lógica exclusiva de Pro aquí
    }
} );

`rpb_should_display`

Se ejecuta justo antes de que ReadNinja decida renderizar o no la barra en la solicitud actual. Devuelve false para ocultarla, true para forzarla. Úsalo para ocultar la barra en artículos muy cortos:

add_filter( 'rpb_should_display', function ( $display, $post_id ) {
    $content    = get_post_field( 'post_content', $post_id );
    $word_count = str_word_count( wp_strip_all_tags( $content ) );

    if ( $word_count < 300 ) {
        return false;
    }
    return $display;
}, 10, 2 );

`rpb_bar_config`

Te da el array de config JS completo justo antes de que se transmita al frontend. Úsalo para inyectar valores personalizados, reemplazar colores basados en meta del artículo, o añadir datos adicionales para tus propios scripts.

add_filter( 'rpb_bar_config', function ( $config ) {
    if ( is_singular( 'podcast' ) ) {
        $config['color']  = '#ff6b35';
        $config['height'] = 6;
    }
    return $config;
} );

`rpb_settings_tabs`

Añade una pestaña personalizada a la página de ajustes. Combínalo con la acción rpb_render_tab_{tab} para rellenar su contenido.

add_filter( 'rpb_settings_tabs', function ( $tabs ) {
    $tabs['custom'] = __( 'Personalizado', 'mi-plugin' );
    return $tabs;
} );

Acciones PHP

Acción	Parámetros	Descripción
`rpb_after_bar_render`	`int $post_id`	Se activa tras la salida del HTML de la barra
`rpb_render_tab_{tab}`	—	Inyecta contenido en cualquier pestaña de ajustes

Ejemplo — añadir un <div> adicional justo después de la barra de progreso en artículos individuales:

add_action( 'rpb_after_bar_render', function ( $post_id ) {
    echo '<div class="my-custom-ribbon" data-post="' . esc_attr( $post_id ) . '"></div>';
} );

Ejemplo — rellenar el contenido de la pestaña personalizada registrada anteriormente:

add_action( 'rpb_render_tab_custom', function () {
    echo '<h2>Mi pestaña personalizada</h2>';
    echo '<p>Cualquier contenido de ajustes va aquí.</p>';
} );

Eventos del navegador

ReadNinja envía un único evento DOM que puedes escuchar en el frontend.

Evento	Objetivo	Detalle
`rpb:threshold-reached`	`document`	`{ percent: number }`

Este evento se activa una sola vez por carga de página, exactamente cuando el lector supera el umbral configurado (funcionalidad Pro — ver Disparador de umbral).

document.addEventListener('rpb:threshold-reached', (e) => {
  console.log('El lector ha alcanzado', e.detail.percent, '%')
  // mostrar un popup, enviar un evento de analytics, etc.
})