Drupal

Meça um site Drupal com o Runlight e veja quando agentes de IA o leem.

O módulo do Runlight roda o Runlight dentro de um site Drupal 10.3 ou 11, com o painel em /runlight no próprio site e os números no banco de dados dele. Ele também pode enviar para um Runlight que você roda em outro lugar, seja o servidor independente ou um app com o Runlight montado, para que um só painel cubra vários sites.

O que ele faz

• Adiciona o script do Runlight a todas as páginas fora do tema de administração. Numa página a que o Drupal responde com 404, o script também registra um evento chamado 404 com o caminho da página que não existe, então as propriedades de 404 no quadro Eventos listam os endereços quebrados que as pessoas acessaram e com que frequência.
• Deixa de fora as visitas de quem pode administrar o Runlight, a menos que você desative isso.
• Informa os agentes de IA como ChatGPT e Claude quando eles leem suas páginas, inclusive páginas respondidas pelo cache de páginas do Drupal. O envio acontece depois que a resposta sai, então a página nunca fica mais lenta.
• Adiciona um item Runlight em Relatórios que mostra o painel deste site na administração.

Configure

Instale o módulo com composer require drupal/runlight e ative-o com drush pm:install runlight, ou em Estender. As configurações dele, em Configuração, Sistema, Runlight, abrem numa tela de configuração inicial, e nada é contado até você escolher onde o Runlight roda. Clique em Run Runlight in this Drupal site e ele começa a contar o site.

Relatórios, Runlight mostra os números, e o botão Open in Runlight abre o painel completo em /runlight no seu site. Ali você pode adicionar metas, funis, links curtos e relatórios por email. Quem tem a permissão Administer Runlight é proprietário deste Runlight. Quem tem a permissão View Runlight vê o mesmo painel sem alterar nada, e todos os outros precisam entrar no Drupal. As mudanças só são aceitas a partir das páginas do seu próprio site, então outro site não consegue fazê-las com a sessão de um proprietário.

Rodar o Runlight dentro do Drupal exige PHP 8.2 ou mais recente com as extensões pdo, mbstring e openssl. A tela de configuração avisa quando falta alguma coisa.

Onde os números ficam guardados

Quando o banco de dados do Drupal é Postgres, MySQL 8.0.20 ou mais recente, ou MariaDB 11.4 ou mais recente, o Runlight guarda os números ali, então seus backups do banco de dados os incluem. As tabelas levam o prefixo de tabelas do Drupal, como rl_events, ou d_rl_events com o prefixo d_, e o Runlight as marca como deste site. Se já existirem tabelas com esses nomes que não sejam do Runlight deste site, como as de um Runlight independente no mesmo banco de dados, ele não mexe nelas e usa um arquivo SQLite. Ele se conecta com uma conexão própria, aberta pelo driver de banco de dados do Drupal com as mesmas configurações do Drupal, então as opções de TLS em pdo e quaisquer init_commands também valem para ela.

Fora isso, os números vão para um arquivo SQLite numa pasta runlight dentro dos arquivos privados do Drupal, o que exige o pdo_sqlite do PHP e uma pasta de arquivos privados, definida com $settings['file_private_path'] no settings.php. O Runlight nunca guarda nada nos arquivos públicos. A escolha é feita na primeira vez que o Runlight roda e nunca muda, então os números nunca se dividem entre dois lugares.

Desinstalar o módulo remove as tabelas do Runlight, cada uma pelo nome e só as deste site, ou a pasta dele, junto com o que ele guardou no state e no cache do Drupal.

Localizações e manutenção

Os países dos visitantes vêm de um cabeçalho quando uma CDN como a Cloudflare envia um. Caso contrário, ative Show which countries visitors come from nas configurações do módulo, e o cron do Drupal baixa uma vez por mês o banco de dados gratuito de países do DB-IP para a pasta do Runlight nos arquivos privados, ou então para a pasta temporária do Drupal. O cron do Drupal também roda a verificação agendada do Runlight, que cria o salt de cada dia, envia os relatórios por email e apaga as visitas além do período de retenção que você definiu, então mantenha o cron rodando, como a maioria dos sites Drupal já faz. Quando a verificação não roda há mais de um dia, a página de configurações avisa.

Endereços dos visitantes

O Runlight conta os visitantes com um hash diário do endereço deles e limita a frequência com que um endereço pode enviar. Ele usa o endereço que o Drupal calcula para cada requisição, que é o endereço da própria conexão, a menos que o settings.php liste os proxies na frente do site, então nenhum visitante consegue escolher um com um cabeçalho. Atrás de um balanceador de carga, de uma CDN ou do proxy de uma hospedagem, informe esses proxies ao Drupal como faria para qualquer outro módulo.

$settings['reverse_proxy'] = TRUE;
$settings['reverse_proxy_addresses'] = ['10.0.0.2'];

As contagens por endereço, e a chave diária usada no hash, ficam no cache do Drupal, em duas entradas que são substituídas a cada minuto e a cada dia.

Contagem

Nas configurações do módulo, Count clicks on links to other sites registra cada clique num link para outro site como um evento chamado Outbound link, e Count file downloads registra cada clique num link para um arquivo, como um PDF ou um zip, como um evento chamado File download. Os dois ficam ativos até você desativá-los.

Conecte-se a um Runlight que você roda em outro lugar

1. Instale e ative o módulo como acima.
2. Na tela de configuração, em Connect to a Runlight you run elsewhere, informe o endereço em que seu Runlight responde, como https://stats.example.com para o servidor independente ou https://example.com/runlight para um app com o Runlight montado. O Runlight mostra esse endereço em Configurações, Instalação, como Endereço do Runlight.
3. Clique em Connect. Seu Runlight pede que você entre, se ainda não entrou, e depois pede que você permita a conexão para o site que conta este domínio. Se nenhum site o conta ainda, ele oferece adicionar um.
4. Clique em Allow. O Runlight manda você de volta ao Drupal com todas as configurações preenchidas, e Relatórios, Runlight mostra os números deste site.

A conexão dá duas chaves ao módulo. A chave de agentes informa os agentes de IA que leem suas páginas, e ela só pode informar leituras deste site, então não consegue ler suas estatísticas nem escrever em outro site. A chave do painel mostra o painel deste site na administração, somente leitura, então trate-a como uma senha. A chave do painel aparece no Runlight em Configurações, API e IA, onde excluí-la desativa o painel no Drupal.

A conexão exige a administração em HTTPS, ou em localhost enquanto você faz testes, já que o Runlight só manda as pessoas de volta para endereços assim. Num app com o Runlight montado, o site já precisa estar em hostnames (veja Configuração), porque ali os sites são definidos no código.

Informe as configurações à mão

Cada configuração do módulo corresponde a um valor no Runlight, em Configurações, Instalação, na seção WordPress, Drupal e Craft, com um botão para copiá-lo. Copie Endereço do Runlight, Chave de agentes e Chave do painel para os campos correspondentes do módulo (Runlight address, Agents key e Dashboard key) e salve. O Runlight mostra a chave do painel uma única vez, então crie uma nova se perdê-la. O Id do site (Site id no módulo) só é necessário quando esse Runlight não consegue reconhecer este site pelo domínio. Quando você salva, a página confere se o endereço responde.

Chaves e ambientes

Onde o Runlight roda, o endereço dele, o id do site e as duas chaves pertencem a um único ambiente, então o módulo os guarda no state do Drupal, que o drush config:export deixa de fora. Eles nunca chegam ao seu repositório, e importar a configuração nunca aponta um ambiente para o Runlight de outro. O que ele conta, como links externos e downloads, continua na configuração e é exportado normalmente. Valores que uma versão anterior do módulo salvou na configuração continuam valendo até você salvar as configurações de novo, o que os move para o state.

Para definir qualquer um deles no código, coloque-os no settings.php, que tem prioridade sobre a página de configurações.

$config['runlight.settings']['address'] = 'https://stats.example.com';
$config['runlight.settings']['observe_key'] = getenv('RUNLIGHT_AGENTS_KEY');
$config['runlight.settings']['dashboard_key'] = getenv('RUNLIGHT_DASHBOARD_KEY');

Relatórios por email

Com o Runlight rodando dentro do Drupal, os relatórios por email e os e-mails de teste passam pelo próprio sistema de envio do Drupal quando o site tem um configurado além do mail() do PHP, como o módulo SMTP, o Symfony Mailer ou o mailer do core com um endereço SMTP. Eles saem do endereço de e-mail do site, com o nome do site, e Configurações, Serviço de e-mail no painel diz qual mailer os envia. Sem um, o painel pede que você configure um serviço de e-mail ali. Você também pode escolher outro serviço enquanto o mailer do Drupal está configurado, e voltar depois ao mailer do Drupal pelo mesmo lugar. Depois de atualizar o módulo, reconstrua os caches do Drupal (drush cr) para que ele encontre o hook que monta esses e-mails.

O painel na administração

Com o Runlight dentro do Drupal, Relatórios, Runlight mostra o painel inteiro, o mesmo de /runlight, com as configurações, as metas e os links curtos. Só páginas do seu próprio site podem exibi-lo num frame.

Com um Runlight em outro lugar e uma chave do painel, a página Relatórios, Runlight mostra o painel deste site na mesma visualização somente leitura que um link de compartilhamento mostra, com os relatórios e os intervalos de datas e sem as configurações, os links curtos, as pessoas ou os outros sites do Runlight. O botão Open in Runlight abre o painel completo no seu próprio Runlight.

O endereço de onde a administração é servida precisa estar entre os domínios do site no Runlight, já que só uma página de administração num deles pode exibir o painel. A conexão cuida disso. Um www. no início não faz diferença.

A chave nunca chega ao navegador. Cada vez que um administrador abre a página, o servidor do módulo envia a chave e a origem do administrador ao Runlight e recebe de volta um ticket que abre o painel uma vez, dentro de cinco minutos. A página carrega o painel do seu Runlight num frame que só esse administrador pode exibir. O frame mantém a sessão na página por uma hora, sem cookies, então navegadores que bloqueiam cookies em frames também o mostram. Quando a hora acaba, o frame avisa e recarrega a página quando você pede. Excluir a chave em Configurações, API e IA do Runlight desativa a chave e todas as sessões abertas na hora. Só quem tem a permissão Administer Runlight ou View Runlight vê a página. Seu Runlight precisa ser servido por HTTPS quando a administração é, ou o navegador recusa o frame.

Quando o Gin é o tema de administração, o frame segue a configuração de modo escuro dele. Com o Claro, ele fica claro.