Faça os sites funcionarem um pouco mais como você deseja.

Comece aqui

How @grant funciona

Para novos scripts, declare todos os API privilegiados que você usa. Social Browser executa scripts com concessões explícitas em um mundo User Script isolado e conecta apenas os recursos solicitados. Um roteiro com @grant none funciona sem recursos de GM.

// ==UserScript==// @name Remember display mode// @namespace https://example.com/my-scripts// @match https://example.com/*// @grant GM_getValue// @grant GM_setValue// ==/UserScript== const mode = GM_getValue('displayMode', 'compact');console.log('Saved mode:', mode); GM_setValue('displayMode', 'comfortable');

Clássico GM_* ou moderno GM.*?

Social Browser suporta os nomes clássicos familiares e seus modernos GM.* forms for the main GM capability set. The modern form is Promise-friendly, so use await. Escolha um estilo por script e mantenha a consistência.

const theme = GM_getValue('theme', 'dark');GM_setValue('theme', 'light');

const theme = await GM.getValue('theme', 'dark');await GM.setValue('theme', 'light');

GM_info / GM.info

Use informações de script quando precisar inspecionar o script atual, versão, concessões, correspondências ou informações de tempo de execução Social Browser. Não codifique o comportamento em torno de strings de versão, a menos que você realmente precise de lógica de compatibilidade.

// @grant GM_info console.log('Script:', GM_info.script.name);console.log('Version:', GM_info.version);console.log('Handler:', GM_info.scriptHandler);console.log('Grants:', GM_info.scriptGrants);console.log('Matches:', GM_info.scriptMatches);

Armazenamento

Lembre-se de pequenos dados de script

O armazenamento GM tem como escopo User Script em vez de ser um armazenamento de página comum. É ideal para preferências, contadores e estados de script inofensivos. Não o use como um cofre casual para senhas, segredos 2FA, cookies ou material de sessão.

// @grant GM_getValue// @grant GM_setValue// @grant GM_deleteValue const settings = GM_getValue('settings', { compact: true, rowsPerPage: 25}); settings.rowsPerPage = 50;GM_setValue('settings', settings); // Reset later if the user asks for defaults.// GM_deleteValue('settings');

Observe uma mudança de valor

GM_addValueChangeListener é útil quando o mesmo script está aberto em mais de um quadro ou guia. O retorno de chamada recebe (name, oldValue, newValue, remote). Em Social Browser, os eventos de alteração de valor podem sincronizar entre quadros/guias no mesmo Profile/sessão.

// @grant GM_addValueChangeListener// @grant GM_removeValueChangeListener const listenerId = GM_addValueChangeListener( 'displayMode', (name, oldValue, newValue, remote) => { console.log({ name, oldValue, newValue, remote }); }); // Remove it when you no longer need it.// GM_removeValueChangeListener(listenerId);

Ajudantes de página

Adicione estilos ou pequenos elementos

GM_addStyle(css) / GM.addStyle(css)

Use isto quando a personalização de uma página for principalmente visual. É mais limpo do que definir muitos element.style propriedades.

// @grant GM_addStyle GM_addStyle(` .important-total { font-weight: 700; outline: 2px solid currentColor; padding: 4px 8px; }`);

GM_addElement(...) / GM.addElement(...)

Crie um pequeno elemento DOM e anexe-o com segurança. Você pode passar um elemento pai primeiro ou omiti-lo para usar o corpo da página.

// @grant GM_addElement const panel = document.querySelector('#account-panel');if (panel) { GM_addElement(panel, 'button', { type: 'button', textContent: 'Copy account ID', className: 'my-copy-button', onclick() { const id = panel.querySelector('.account-id')?.textContent?.trim(); if (id) navigator.clipboard.writeText(id); } });}

Rede

Faça solicitações privilegiadas com GM_xmlhttpRequest

Página normal fetch() é controlado pelas regras normais do navegador/CORS da página. A solicitação GM de Social Browser API usa um canal de solicitação de processo de navegador dedicado. Antes de uma solicitação ser enviada, seu destino é verificado em relação ao script @connect regras.

// ==UserScript==// @match https://app.example.com/*// @connect api.example.com// @grant GM_xmlhttpRequest// ==/UserScript== const response = await GM_xmlhttpRequest({ method: 'GET', url: 'https://api.example.com/status', responseType: 'json', timeout: 10000, headers: { Accept: 'application/json' }}); console.log(response.status, response.response);

Retornos de chamada e aborto

A solicitação API oferece suporte a retornos de chamada de solicitação comuns e retorna um identificador que pode ser anulado. Use um tempo limite mesmo quando você também suporta o aborto.

// @connect api.example.com// @grant GM_xmlhttpRequest const request = GM_xmlhttpRequest({ url: 'https://api.example.com/slow-report', timeout: 15000, onload(response) { console.log('Loaded:', response.status); }, onerror(error) { console.error('Request failed:', error); }, ontimeout() { console.warn('Request timed out'); }, onabort() { console.log('Request aborted'); }}); // Cancel only if your script no longer needs the result.// request.abort();

Forma moderna: GM.xmlHttpRequest(...) and GM.xmlhttpRequest(...) mapear para o mesmo recurso de solicitação.

Recursos

Agrupar texto reutilizável, CSS ou outros ativos

Declarar um ativo com @resourcee leia-o pelo nome. GM_getResourceText returns decoded text. GM_getResourceURL returns a data URL that preserves the response MIME type.

// ==UserScript==// @resource helperCss https://example.com/assets/helper.css// @grant GM_getResourceText// @grant GM_getResourceURL// ==/UserScript== const css = await GM_getResourceText('helperCss');console.log(css); const dataUrl = await GM_getResourceURL('helperCss');console.log(dataUrl);

Se o nome do recurso não existir, API retornará undefined. Mantenha os nomes dos recursos curtos e descritivos.

Ajudantes do navegador

Guias, notificações e área de transferência

GM_openInTab(url, options)

Abra um URL em uma guia Social Browser. Usar active: false quando a nova guia deve abrir sem tirar o foco.

// @grant GM_openInTab GM_openInTab('https://example.com/report', { active: false});

Estado do script por guia: GM_getTab, GM_saveTab, GM_getTabs

Esses APIs armazenam pequenos estados User Script associados às guias. Eles são úteis quando um script precisa lembrar qual etapa ou visualização pertence a uma guia específica sem misturá-la com preferências globais de script.

// @grant GM_getTab// @grant GM_saveTab// @grant GM_getTabs const tabState = await GM_getTab();await GM_saveTab({ ...tabState, lastPanel: 'orders'}); const allScriptTabs = await GM_getTabs();console.log(allScriptTabs);

GM_notification

Mostrar uma notificação do navegador sobre algo que o usuário realmente deveria notar. Evite spam de notificação para atividades rotineiras de script.

// @grant GM_notification await GM_notification({ title: 'Report ready', text: 'The page data is ready to review.'});

GM_setClipboard(data, type)

Copie o texto (ou HTML quando solicitado) para a área de transferência. Use-o após uma ação clara do usuário, quando possível, para que o usuário entenda por que sua área de transferência foi alterada.

// @grant GM_setClipboard const orderId = document.querySelector('.order-id')?.textContent?.trim();if (orderId) { GM_setClipboard(orderId, 'text');}

Menus e downloads

Adicione ações deliberadas do usuário

GM_registerMenuCommand / GM_unregisterMenuCommand

Registre um comando no menu User Script. Este é um bom padrão para ações que devem acontecer somente quando o usuário as solicitar explicitamente.

// @grant GM_registerMenuCommand// @grant GM_unregisterMenuCommand const commandId = GM_registerMenuCommand( 'Highlight overdue rows', () => { document.querySelectorAll('.row.overdue').forEach((row) => { row.style.fontWeight = '700'; }); }); // Remove the menu item later if the script no longer needs it.// GM_unregisterMenuCommand(commandId);

GM_download

Inicie um download por meio de Social Browser. Dê ao arquivo um nome claro e use-o somente quando o download fizer parte do propósito visível do script.

// @grant GM_download await GM_download({ url: 'https://example.com/reports/today.csv', name: 'today-report.csv'});

Avançado

unsafeWindow: ponte para páginas globais somente quando necessário

User Scripts de concessão explícita normalmente é executado em um mundo isolado. unsafeWindow é uma ponte opcional para globais no mundo PRINCIPAL da página. Use-o somente quando o site expõe uma variável ou função de página que o acesso comum por script isolado não consegue alcançar.

// @grant unsafeWindow const appVersion = unsafeWindow.appConfig?.version;if (appVersion) { console.log('Page app version:', appVersion);}

Regra do mundo de execução

Exemplo completo

Um pequeno script que combina armazenamento, estilos, comandos de menu e área de transferência

Este exemplo permanece intencionalmente pequeno. Ele lembra se o realce está habilitado, adiciona uma regra de estilo, permite ao usuário alterná-lo no menu User Script e copia um valor de página visível somente quando solicitado.

// ==UserScript==// @name Helpful order-page tools// @namespace https://example.com/my-scripts// @version 1.0.0// @match https://example.com/orders/*// @grant GM_getValue// @grant GM_setValue// @grant GM_addStyle// @grant GM_registerMenuCommand// @grant GM_setClipboard// ==/UserScript== (() => { 'use strict';  GM_addStyle(` .sb-order-highlight { outline: 2px solid currentColor; font-weight: 700; } `);  const applyHighlight = () => { const enabled = GM_getValue('highlightEnabled', true); document.querySelectorAll('.order-total').forEach((element) => { element.classList.toggle('sb-order-highlight', enabled); }); };  GM_registerMenuCommand('Toggle order highlighting', () => { const current = GM_getValue('highlightEnabled', true); GM_setValue('highlightEnabled', !current); applyHighlight(); });  GM_registerMenuCommand('Copy current order ID', () => { const orderId = document.querySelector('.order-id')?.textContent?.trim(); if (orderId) { GM_setClipboard(orderId, 'text'); } });  applyHighlight();})();