Hooks & Filtros

Esta referência é destinada a desenvolvedores que desejam estender o ReadNinja de forma programática. Todos os hooks e filtros são estáveis e disponíveis nas versões Gratuita e Pro.

Filtros PHP

Filtro	Parâmetros	Descrição
`rpb_is_pro`	`bool`	Retorna `true` se a licença Pro estiver ativa
`rpb_should_display`	`bool $display, int $post_id`	Controla programaticamente se a barra é renderizada
`rpb_bar_config`	`array $config`	Modifica o array de configuração JS antes de ser enviado para a página
`rpb_settings_tabs`	`array $tabs`	Adiciona ou remove abas na página de configurações

`rpb_is_pro`

Permite que outros plugins verifiquem se o Pro está ativo sem codificar nomes de classes ou constantes.

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

`rpb_should_display`

Executa logo antes de o ReadNinja decidir renderizar ou não a barra na requisição atual. Retorne false para ocultá-la, true para forçá-la. Use-o para ocultar a barra em artigos muito curtos:

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`

Fornece o array de configuração JS completo logo antes de ser transmitido para o front-end. Use-o para injetar valores personalizados, substituir cores baseadas em meta do artigo ou adicionar dados extras para seus próprios scripts.

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

`rpb_settings_tabs`

Adiciona uma aba personalizada à página de configurações. Combine com a action rpb_render_tab_{tab} para preencher o conteúdo.

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

Actions PHP

Action	Parâmetros	Descrição
`rpb_after_bar_render`	`int $post_id`	Dispara após a saída do HTML da barra
`rpb_render_tab_{tab}`	—	Injeta conteúdo em qualquer aba de configurações

Exemplo — adicionar uma <div> extra logo após a barra de progresso em artigos individuais:

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

Exemplo — preencher o conteúdo da aba personalizada registrada acima:

add_action( 'rpb_render_tab_custom', function () {
    echo '<h2>Minha aba personalizada</h2>';
    echo '<p>Qualquer conteúdo de configurações vai aqui.</p>';
} );

Eventos do navegador

O ReadNinja envia um único evento DOM que você pode escutar no front-end.

Evento	Alvo	Detalhe
`rpb:threshold-reached`	`document`	`{ percent: number }`

Este evento dispara uma única vez por carregamento de página, exatamente quando o leitor ultrapassa o gatilho configurado (funcionalidade Pro — consulte Gatilho de porcentagem).

document.addEventListener('rpb:threshold-reached', (e) => {
  console.log('O leitor atingiu', e.detail.percent, '%')
  // exibir um popup, enviar um evento de analytics, etc.
})