Execução de scripts em páginas com parâmetros específicos usando Tampermonkey

Ao lidar com scripts de automação ou personalização de páginas web, uma dificuldade comum é determinar o momento exato de disparar uma ação, especialmente quando o URL possui parâmetros dinâmicos. Nesse cenário, o uso de diretivas de correspondência como @match e @include no Tampermonkey apresenta limitações que podem impactar a confiabilidade do script.

Problema Concreto

A principal questão é como garantir que um script seja executado apenas em URLs que contenham determinados parâmetros, independentemente da ordem, presença de outros parâmetros ou se eles estão na posição inicial ou intermediária da query string. Por padrão, o @match só funciona com o esquema, host e caminho da URL, sem considerar os parâmetros de consulta. Assim, um @match simples como http://example.com/page.php?key1=value1 não disparará se outros parâmetros estiverem presentes ou se key1 não for o primeiro parâmetro.

Diagnóstico

A limitação do @match está na sua capacidade de fazer correspondência apenas na estrutura fixa do URL. Como ele não analisa a query string, scripts que dependem de parâmetros específicos precisam de uma abordagem adicional. O método mais comum é fazer uma verificação manual com location.search ou location.href, usando expressões regulares ou funções de parsing. Sem esse critério, a solução pode parecer simples no começo e cara no suporte.

Por exemplo, location.search retorna a parte da query string, começando com '?'. Para identificar se um parâmetro específico está presente, uma estratégia eficiente é usar uma expressão regular que procura por uma palavra-chave com seu valor, garantindo que não haja falsos positivos.

Abordagem de Solução

A melhor prática é usar uma combinação de @match com uma correspondência geral na URL e verificar os parâmetros via código. Assim, o script é carregado em todas as páginas relevantes, mas só executa sua lógica se os parâmetros desejados forem encontrados. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, prodto e engenharia olham para o mesmo risco.

Um padrão recomendado é:

// @match *://example.com/page.php*

if (/\bkey1=value1\b/.test(location.search)) {
  // Executa a ação desejada
}

Isso garante que o script seja carregado em qualquer URL que contenha page.php, e a checagem dentro do código garante a presença exata do parâmetro.

Limites e Trade-offs

A abordagem de verificar location.search após o carregamento é eficiente, mas tem suas limitações. Se a URL for muito complexa ou se houver necessidade de manipular múltiplos parâmetros de forma dinâmica, o código pode ficar mais difícil de manter. Além disso, se o site usar URLs altamente dinâmicos ou de uma aplicação SPA, a checagem precisa ser feita também em eventos de navegação interna, não apenas na carga inicial. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar.

Para cenários mais avançados, o uso de funções de parsing de query string, como URLSearchParams, melhora a legibilidade e a confiabilidade: O valor aparece melhor quando operação, produto e engenharia olham para o mesmo risco. A decisão fica mais saudável quando o time consegue medir o impacto depois. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. A decisão fica mais saudável quando o time consegue medir o impacto depois. A decisão fica mais saudável quando o time consegue medir o impacto depois. A decisão fica mais saudável quando o time consegue medir o impacto depois.

const params = new URLSearchParams(location.search). if (params.get('key1') === 'value1') {
  // sua lógica aqui
}

Passos Acionáveis

1. Configure o @match para uma URL geral, como ://example.com/page.php, para garantir que o script seja carregado em todas as variações.
2. Dentro do script, utilize URLSearchParams para verificar a existência e valor do parâmetro.
3. Para páginas com navegação dinâmica, considere escutar eventos de navegação do seu framework ou usar mutações no DOM para detectar mudanças de URL.
4. Caso precise de uma correspondência mais complexa ou condições adicionais, combine regex com verificações no código.

Conclusão

Para garantir execução condicional de scripts em páginas com parâmetros específicos, o melhor é evitar confiar apenas no @match. Em vez disso, combine uma correspondência ampla com verificações programáticas de parâmetros, garantindo maior controle e confiabilidade na automação. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta. Por isso, o recorte precisa considerar manutenção, validação e caminho de volta.

Essa estratégia evita problemas com URLs de diferentes ordens de parâmetros ou com URLs parcialmente carregadas, além de facilitar a manutenção em ambientes de URLs dinâmicos ou de aplicações SPA. A decisão fica mais saudável quando o time consegue medir o impacto depois. Sem esse critério, a solução pode parecer simples no começo e cara no suporte. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar. A decisão fica mais saudável quando o time consegue medir o impacto depois. Esse contexto ajuda a separar ganho real de novidade difícil de sustentar.