Craft CMS

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

O plugin do Runlight roda o Runlight dentro de um site Craft 5, 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 do front-end. Numa página a que o Craft 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 dos próprios usuários do Control Panel, a menos que você desative isso. As páginas que eles veem sem o script nunca vão para o cache, então todos os outros continuam recebendo o script.
• Informa os agentes de IA como ChatGPT e Claude quando eles leem suas páginas, depois que a conexão é fechada, então o agente nunca espera pelo envio.
• Adiciona ao Control Panel um item Runlight que mostra ali o painel deste site.

Configure

Instale o plugin rodando composer require runlight/craft e depois php craft plugin/install runlight, ou em Settings, Plugins. As configurações dele abrem numa tela de configuração inicial, e nada é contado até você escolher onde o Runlight roda. Clique em Run Runlight in this Craft site e ele começa a contar o site.

O item Runlight no Control Panel 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. Os admins, e as pessoas com a permissão Manage Runlight, são proprietários deste Runlight. As pessoas com a permissão See Runlight’s numbers veem o mesmo painel sem alterar nada. As duas ficam em Users, Permissions, Runlight, e todos os outros precisam entrar no Craft. 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 Craft 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 Craft é 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 e todos os servidores de um site veem os mesmos números. As tabelas levam o prefixo de tabelas do Craft, como craft_rl_events, e o Runlight as marca como desta instalação. Se já existirem tabelas com esses nomes que não sejam do Runlight desta instalação, como as de um Runlight independente no mesmo banco de dados, ele não mexe nelas e usa um arquivo SQLite. Fora isso, os números vão para um arquivo SQLite em storage/runlight, que a web nunca serve, e que exige o pdo_sqlite do PHP. Um arquivo SQLite pertence a um único servidor, então com vários servidores, ou numa hospedagem que substitui storage a cada deploy, use um banco de dados em que o Runlight possa guardar os números.

Nada registra a escolha ao lado dos números. Tabelas do Runlight no banco de dados do Craft significam o banco de dados do Craft, e um arquivo SQLite significa SQLite, então a escolha se mantém em todos os servidores e em todos os deploys. O segredo com que o Runlight assina as sessões, e com que protege as chaves que você salva no painel dele, vem do securityKey do Craft, então também é o mesmo em todo lugar. Mudar o securityKey encerra a sessão de todo mundo no Runlight, e as chaves salvas no painel, como as de um serviço de e-mail, precisam ser informadas de novo.

Desinstalar o plugin remove as tabelas do Runlight, cada uma pelo nome e só as desta instalação, mesmo quando storage/runlight não existe mais, e também a pasta dele.

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 Locations nas configurações do plugin, e a manutenção baixa uma vez por mês o banco de dados gratuito de países do DB-IP para storage/runlight em cada servidor. A manutenção 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. Uma visita ao site a coloca na fila no máximo uma vez por hora, e só enquanto nenhuma anterior estiver esperando. A fila do Craft só roda enquanto alguém usa o Control Panel, a menos que haja um executor de fila configurado, então adicione php craft runlight/check ao cron do seu servidor, de hora em hora. Quando a manutençã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 Craft calcula para cada requisição, que segue as configurações trustedHosts e ipHeaders do Craft. O Craft confia nos cabeçalhos de proxy de qualquer host até você indicar quais ficam na frente do seu site, então defina trustedHosts em config/general.php, ou CRAFT_TRUSTED_HOSTS, com os endereços do seu balanceador de carga ou da sua CDN, e nenhum visitante conseguirá escolher um endereço com um cabeçalho.

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

Contagem

Nas configurações do plugin, 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 o plugin 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 Craft com todas as configurações preenchidas, e o item Runlight no Control Panel mostra os números deste site.

A conexão dá duas chaves ao plugin. 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 no Control Panel, 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 Craft.

A conexão exige o Control Panel 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.

A conexão grava as chaves no arquivo .env do Craft, como RUNLIGHT_AGENTS_KEY e RUNLIGHT_DASHBOARD_KEY, e salva as configurações como $RUNLIGHT_AGENTS_KEY e $RUNLIGHT_DASHBOARD_KEY, para que o project config cite as variáveis e não guarde nenhuma chave. Cada ambiente define então as suas. Quando não é possível gravar no .env, o Connect salva as chaves nas próprias configurações e explica como movê-las.

Informe as configurações à mão

Cada configuração do plugin 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 plugin (Runlight address, Agents key e Dashboard key) e salve, ou para o .env como acima. 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 plugin) só é necessário quando esse Runlight não consegue reconhecer este site pelo domínio. Depois que a página carrega, ela confere se o endereço responde.

Qualquer configuração pode citar uma variável de ambiente, como $RUNLIGHT_URL. Se você mudar o endereço, as chaves que salvou para o antigo são apagadas, para que uma chave nunca seja enviada a outro Runlight. Informe-as de novo para o novo endereço, ou clique em Connect. Como em qualquer plugin do Craft, todas as configurações também podem vir de config/runlight.php, e os valores ali têm prioridade sobre o Control Panel.

<?php
return [
    'address' => 'https://stats.example.com',
    'observeKey' => '$RUNLIGHT_AGENTS_KEY',
    'dashboardKey' => '$RUNLIGHT_DASHBOARD_KEY',
];

Relatórios por email

Com o Runlight rodando dentro do Craft, os relatórios por email e os e-mails de teste passam pelo próprio mailer do Craft quando Settings, Email usa um transporte diferente do Sendmail, como SMTP ou o plugin de um serviço de e-mail. Eles saem do endereço de e-mail do sistema e com o nome de remetente do Craft, e Configurações, Serviço de e-mail no painel diz qual transporte os envia. Com o Sendmail, 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 Craft está configurado, e voltar depois ao mailer do Craft pelo mesmo lugar.

O painel no Control Panel

Com o Runlight dentro do Craft, o item Runlight mostra o painel inteiro no Control Panel, 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, então quando o Control Panel é servido de outro endereço, definido com baseCpUrl, o item abre o painel numa nova aba.

Com um Runlight em outro lugar e uma chave do painel, o item Runlight mostra o painel deste site no Control Panel, 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 o Control Panel é servido 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 da página do painel. (Digitada diretamente, ela aparece sim no formulário de configurações, que só os admins veem, então uma variável de ambiente é melhor.) Cada vez que um administrador abre a página, o servidor do plugin 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 pode acessar o plugin do Runlight, admins incluídos, vê a página. Seu Runlight precisa ser servido por HTTPS quando o Control Panel é, ou o navegador recusa o frame.

Cache estático

Caches estáticos como o Blitz servem as páginas sem rodar o Craft, ou param o Craft antes de a página ser enviada. Essas páginas continuam incluindo o script, então as visitas são contadas. Uma página que um usuário do Control Panel vê sem o script nunca vai para o cache: o plugin diz ao Blitz para não guardá-la e envia cabeçalhos que impedem outros caches de armazená-la. As leituras de agentes de IA nas páginas em cache não são informadas, porque o plugin nunca tem a chance de vê-las.