Расширения

Пользовательские скрипты

Пользовательские скрипты (мы также называем их «‎расширениями»‎) — это мини-программы, написанные на языке JavaScript. Они модифицируют или расширяют функциональность одного или нескольких сайтов. Многие пользователи AdGuard уже наверняка знакомы с такими расширениями, как Помощник AdGuard, Блокировщик всплывающих окон и AdGuard Extra.

Поддерживаемые приложения

AdGuard может значительно расширять функциональность сайтов, работая как менеджер пользовательских скриптов. Вы можете добавлять собственные скрипты или управлять существующими в наших трёх продуктах: AdGuard для Windows, AdGuard для Android и AdGuard для Mac.

Рекомендуемые скрипты AdGuard

Эти пользовательские скрипты разработаны в AdGuard, и мы можем гарантировать, что они эффективны и безопасны. Есть и другие пользовательские скрипты, разработанными другими людьми, которые мы считаем хорошими и надёжными. Чтобы ознакомиться с ними, прокрутите страницу вниз [до следующего раздела[(#top-picks). Вы также можете найти популярные сайты со скриптами ниже. Помните, что скачивать пользовательские скрипты из неизвестных источников может быть небезопасно.

AdGuard Extra

Расширение, которое блокирует рекламу в сложных случаях, когда привычного подхода, основанного на фильтрах, недостаточно. AdGuard Extra предустановлен и включён по умолчанию в AdGuard для Windows, AdGuard для Mac и AdGuard для Android (в платной версии). Если вы хотите использовать AdGuard Extra вместе с Браузерным расширением AdGuard или любым другим блокировщиком рекламы, вам понадобится установить отдельное расширение. На GitHub есть подробности об этом пользовательском скрипте и о том, как его установить.

Блокировщик всплывающих окон

Этот пользовательский скрипт блокирует один из самых раздражающих типов рекламы — всплывающие окна. На GitHub есть подробности об этом пользовательском скрипте и о том, как его установить.

Помощник AdGuard (устаревшая версия)

Это расширение предназначено для управления фильтрацией прямо со страницы браузера: например, оно позволяет заблокировать элементы вручную или добавить сайт в белый список.

комментарий

Это устаревшая версия Помощника. Её нет смысла использовать на новых системах, потому что её давно заменил полнноценный Браузерный помощник. Но предыдущая версия Помощника может пригодиться, если для вашего браузера нет Браузерного помощника. Если это ваш случай, перейдите на GitHub, чтобы установить Помощник AdGuard.

Отключить AMP

Скрипт, который предустановлен только в AdGuard для Android. Он отключает AMP (Accelerated Mobile Pages или «ускоренные мобильные страницы») на странице результатов поиска Google. На GitHub есть подробности об этом пользовательском скрипте и о том, как его установить.

Лучшие варианты вне AdGuard

Эти пользовательские скрипты не разработаны AdGuard, поэтому мы не можем дать 100% гарантию, что они безопасны и/или работают всегда. Однако, исходя из нашего опыта, они заслуживают рекомендации, поскольку заслужили свою хорошую репутацию.

Don't track me Google

Этот скрипт удаляет функцию отслеживания Google из ссылок в результатах поиска Google. Это ускоряет загрузку результатов поиска и позволяет скопировать URL-адрес ссылки, щёлкнув по нему правой кнопкой мыши или нажав на него.

Его исходный код доступен на GitHub. Этот пользовательский скрипт можно скачать с сайта GreasyFork и установить с помощью любого приложения AdGuard на основе CoreLibs (AdGuard для Windows, AdGuard для Mac и AdGuard для Android).

tinyShield

Пользовательский скрипт для тех, кто посещает корейские и некоторые международные сайты. Скрипт блокирует рекламу Ad-Shield и программы, обходящие блокировщики рекламы. Этот пользовательский скрипт можно установить с помощью приложений AdGuard на основе CoreLibs, а также с помощью Violentmonkey, Tampermonkey и quoid/userscripts. На GitHub есть подробности об этом пользовательском скрипте и о том, как его установить.

Где взять больше пользовательских скриптов

По большей части пользовательские скрипты создаются любителями, поэтому, устанавливая тот или иной скрипт, нужно быть очень осторожными. Любой скрипт из неизвестного источника несёт в себе потенциальный риск. Тем не менее, существует огромное количество интересных скриптов, которые, если установить их аккуратно и ответственно, могут сделать сайты удобнее.

Здесь мы опишем несколько популярных каталогов пользовательских скриптов.

Userscript.Zone

Userscript.Zone — это сайт, который позволяет искать пользовательские скрипты по URL или домену. Сайт простой в использовании и надёжный: он отображает скрипты только с модерируемых страниц.

Greasy Fork

Greasy Fork — это каталог пользовательских скриптов от создателей Stylish. Скрипты в этом каталоге проходят модерацию.

OpenUserJS.org

OpenUserJS.org — каталог пользовательских скриптов с открытым кодом, разработанный с использованием Node.js. Он не модерируется, поэтому проверяйте скрипты внимательно.

Сообщество

Если вы хотите персонализировать браузер при помощи пользовательских скриптов и у вас есть вопросы на эту тему, задать их можно на любом из этих сайтов:

• Stackoverflow
• FreeNode
• Reddit

Разработка

Запросить лицензию

Если вы разрабатываете собственный пользовательский скрипт и хотите протестировать, как он работает с AdGuard, вы можете запросить лицензию, заполнив форму.

Совместимость

Блок метаданных

Поддерживаемые свойства

• @name
• @namespace
• @description
• @version
• @match
• @include
• @exclude
• @grant
• @connect
• @require
• @resource
• @downloadURL
• @updateURL
• @homepage, @homepageURL, @source, @website
• @run-at
• @noframes
• @icon, @iconURL, @defaulticon
• @icon64, @icon64URL

Неподдерживаемые свойства

AdGuard проигнорирует эти свойства.

• @unwrap

Поддерживаемые функции GM

AdGuard поддерживает как старые функции GM_, так и новый GM4 API, использующий объект GM.

комментарий

Все перечисленные функции Greasemonkey устарели, но всё ещё поддерживаются.

• GM.info, GM_info
• GM.setValue, GM_setValue
• GM.getValue, GM_getValue
• GM.listValues, GM_listValues
• GM.deleteValue, GM_deleteValue
• GM.getResourceUrl, GM_getResourceURL
• GM.setClipboard, GM_setClipboard
• GM.xmlHttpRequest, GM_xmlhttpRequest
• GM.openInTab, GM_openInTab
• GM.notification
• unsafeWindow
• GM_getResourceText
• GM_addStyle
• GM_log
• GM.addElement, GM_addElement

Подробную информацию об API Greasemonkey можно найти в руководстве.

Пример

// ==UserScript==
// @name            Name as shown to the user when locale is english or unknown
// @name:ru         Name as shown to the user when locale is russian
// @description     Description as shown to the user when locale is english or unknown
// @description:ru  Description as shown to the user when locale is russian
// @icon            https://myhomepage.com/myuserscript.png
// @version         1.0.0.0
// @downloadURL     https://dl.myhomepage.org/myuserscript.user.js
// @updateURL       https://dl.myhomepage.org/myuserscript.meta.js
// @homepageURL     https://myhomepage.com/myuserscript
// @include         *
// @exclude         *://website.com/*
// @resource        https://myhomepage.com/myuserscript.css
// @require         https://myhomepage.com/mylibrary.js
// @grant           property:settings
// @grant           GM_getValue
// @grant           GM_setValue
// @grant           GM_deleteValue
// @grant           GM_listValues
// @grant           GM_getResourceText
// @grant           GM_getResourceURL
// @grant           GM_addStyle
// @grant           GM_log
// @grant           GM_setClipboard
// @grant           GM_xmlhttpRequest
// @grant           unsafeWindow
// @grant           GM_info
// @grant           GM_openInTab
// @grant           GM_registerMenuCommand
// @grant           GM_addElement
// @run-at          document-start
// ==/UserScript==
!function(){(
    console.log("I am loaded!");
)}();

Trusted Types API

AdGuard provides an instance of the PolicyApi class that allows you to manage Trusted Types in your userscripts.

You can access the instance of this class by using the ADG_policyApi variable in your userscript.

Свойства

• name: string — название политики (по умолчанию AGPolicy).
• isSupported: boolean — флаг, указывающий, поддерживается ли API Trusted Types текущим браузером.

Polyfilled methods

• ADG_policyApi.createHTML. Если не поддерживается, возвращает input: string.
• ADG_policyApi.createScript. Если не поддерживается, возвращает input: string.
• ADG_policyApi.createScriptURL. Если не поддерживается, возвращает input: string.
• ADG_policyApi.getAttributeType. Если не поддерживается, возвращает null.
• ADG_policyApi.getPropertyType. Если не поддерживается, возвращает null.
• ADG_policyApi.isHTML. Если не поддерживается, возвращает false.
• ADG_policyApi.isScript. Если не поддерживается, возвращает false.
• ADG_policyApi.isScriptURL. Если не поддерживается, возвращает false.

Additional Types

/**
 * Enum representation of the return values of the `getAttributeType` and
 * `getPropertyType` methods of the native Trusted Types API.
 *
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/getAttributeType}
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/getPropertyType}
 */
enum TrustedType {
    HTML = 'TrustedHTML',
    Script = 'TrustedScript',
    ScriptURL = 'TrustedScriptURL',
}

// You can access it like that inside of userscript
ADG_TrustedType.HTML // "TrustedHTML"

/**
 * Isomorphic trusted value type. If a browser supports the Trusted Types API, it will be one of the enum Trusted Types
 * (`TrustedHTML`, `TrustedScript` or `TrustedScriptURL`); otherwise, it will be regular `string`.
 *
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedHTML}
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedScript}
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedScriptURL}
 */
type TrustedValue = string | TrustedHTML | TrustedScript | TrustedScriptURL;

Дополнительные методы

/**
 * Creates a Trusted Type depending on `type`:
 * - `TrustedHTML`
 * - `TrustedScript`
 * - `TrustedScriptURL`
 * - or returns `value` if none of them is applicable.
 *
 * @param type          Trusted Type.
 * @param value         Value from which a Trusted Type is created.
 * @param createArgs    Additional arguments to be passed to the function represented by `TrustedTypePolicy`.
 * @returns             Created value.
 */
function create(
    type: TrustedType,
    value: string,
    ...createArgs: unknown[]
): TrustedValue


// Example: Creates TrustedHTML
const trustedHTML = ADG_policyApi.create(ADG_TrustedType.HTML, '<div></div>');

/**
 * Converts `value` of `attribute` into one of the Trusted Types:
 * - `TrustedHTML`
 * - `TrustedScript`
 * - `TrustedScriptURL`
 * - or returns `value` if none of them is applicable.
 *
 * @param tagName       Name of an HTML tag.
 * @param attribute     Attribute.
 * @param value         Value of an attribute to be converted.
 * @param elementNS     Element namespace. If empty, defaults to the HTML namespace.
 * @param attrNS        Attribute namespace. If empty, defaults to null.
 * @param createArgs    Additional arguments to be passed to the function represented by `TrustedTypePolicy`.
 * @returns             Converted value.
 */
function convertAttributeToTrusted(
    tagName: string,
    attribute: string,
    value: string,
    elementNS?: string,
    attrNS?: string,
    ...createArgs: unknown[]
): TrustedValue

// Example: Converts to TrustedScriptURL
const trustedScriptURL = ADG_policyApi.convertAttributeToTrusted("script", "src", 'SOME_URL');
scriptElement.setAttribute("src", trustedScriptURL);

/**
 * Converts `value` of `property` into one of the Trusted Types:
 * - `TrustedHTML`
 * - `TrustedScript`
 * - `TrustedScriptURL`
 * - or returns `value` if none of them is applicable.
 *
 * @param tagName       Name of an HTML tag.
 * @param property      Property.
 * @param value         Value of a property to be converted.
 * @param elementNS     Element namespace. If empty, defaults to the HTML namespace.
 * @param createArgs    Additional arguments to be passed to the function represented by `TrustedTypePolicy`.
 * @returns             Converted value.
 */
function convertPropertyToTrusted(
    tagName: string,
    property: string,
    value: string,
    elementNS?: string,
    ...createArgs: unknown[]
): TrustedValue

// Example: Converts to TrustedHTML
divElement.innerHTML = ADG_policyApi.convertPropertyToTrusted("div", "innerHTML", "<div></div>");

Пользовательские стили

Пользовательские стили позволяют изменять внешний вид популярных сайтов.

В AdGuard есть возможность загружать или создавать собственные пользовательские стили. Это продвинутая функция, поэтому вам понадобятся некоторые знания HTML и CSS.

Поддерживаемые приложения

Сейчас создавать и управлять пользовательскими стилями можно в двух приложениях AdGuard: AdGuard для Windows (версии 7.19 или выше) и AdGuard для Mac (версии 2.16 или выше). We also plan to implement this new feature in AdGuard for Android v4.8 in the nearest future.

Это экспериментальная функция. Поэтому, если вы столкнётесь с проблемами при добавлении или создании пользовательского стиля, пожалуйста, напишите нашей команде поддержки на почту support@adguard.com.

Как настроить пользовательский стиль в AdGuard

Вы можете скачивать пользовательские стили с разных сайтов. Один из самых популярных сайтов — https://userstyles.world/. Возьмём его в качестве примера.

1. Перейдите по ссылке выше и выберите пользовательский стиль, который вам нравится

2. Нажмите Copy (Копировать) рядом с URL-адресом стиля

3. Откройте настройки AdGuard → Расширения

4. Нажмите на кнопку [+] и вставьте ссылку на пользовательский стиль

5. Готово!

Если вы знакомы с правилами CSS, вы также можете создавать пользовательские стили самостоятельно.

комментарий

Мы не поддерживаем пользовательские стили, которые содержат @var или @advanced в метаданных. AdGuard также не поддерживает @preprocessor без значения default.

1. Откройте настройки AdGuard → Расширения

2. Нажмите на кнопку [+] и выберите опцию Создать стиль. Откроется новое окно

3. Чтобы создать пользовательский стиль, сначала напишите заголовок с метаданными, например:

   /* ==UserStyle==
   @name New userstyle
   @version 1.0
   ==/UserStyle== */

4. После метаданных добавьте сам пользовательский стиль на основе CSS. AdGuard поддерживает доменные имена, соответствующие (@-moz-document domain(…), …). Например:

   body {
     background: gray;
     }

   Или:

   @-moz-document domain('example.org'),
   domain('example.net'),
   domain('example.com') body {
     background: gray;
     }

5. Когда закончите, нажмите Сохранить и закрыть. Готово, пользовательский стиль добавлен в AdGuard

Пример

/* ==UserStyle==
@name         Example userstyle
@namespace    https://example.org/userstyle
@homepageURL  https://example.org/userstyle
@version      1.0.0
@license      Other
@description  This is an example
@author       example
@preprocessor default
==/UserStyle== */
@-moz-document regexp("https?\:\/\/(www\.)?example\.(org|com).*") {
    body {
        background-color: #000000 !important;
    }
}