SERPINFO

SERPINFO is the mechanism that allows uBlacklist to work on search engines such as Google, Bing, and DuckDuckGo. Each SERPINFO is a YAML file that describes how to locate search results on a specific search engine's results page, so that uBlacklist can block, highlight, or attach buttons to them.

uBlacklist ships with built-in SERPINFO definitions for the supported search engines. You can also subscribe to SERPINFO published by others, or write your own to support a search engine that is not yet covered.

The SERPINFO options page is opened from Other search engines on the extension's options page. There you can enable or disable individual SERPINFO, subscribe to ones published by others, and write your own under My SERPINFO.

Dateiformat

SERPINFO-Dateien verwenden das YAML-Format mit der folgenden Struktur:

name: SearchEngineName
version: 1.0.0
homepage: https://example.com/
lastModified: 2023-09-01T00:00:00Z

pages:
  - name: PageType
    matches:
      - https://search.example.com/search?*
    results:
      - root: .result-selector
        url: a.link
        props:
          title: .title
    commonProps:
      $site: example
      $category: web

Top-Level-Eigenschaften

Erforderlich	Eigenschaft	Typ	Beschreibung
✓	`name`	string	Name des SERPINFO
✓	`pages`	array	Array der Seitendefinitionen
	`version`	string	Version des SERPINFO
	`description`	string	Beschreibung des SERPINFO
	`homepage`	string	Homepage-URL des SERPINFO
	`lastModified`	string	Letzte Änderungszeit im ISO-Format

Seitendefinition

Jedes Element im Array pages repräsentiert einen bestimmten Typ der Suchergebnisseite (Web, Bilder, Nachrichten usw.):

Erforderlich	Eigenschaft	Typ	Beschreibung
✓	`name`	string	Name der Seitendefinition
✓	`matches`	array	Array von übereinstimmenden Mustern zum Einbeziehen von Seiten
✓	`results`	array	Array der Ergebnisdefinitionen
	`excludeMatches`	array	Array von übereinstimmenden Mustern zum Ausschließen von Seiten
	`includeRegex`	string	Reguläres Ausdrucksmuster zum Einschließen von Seiten
	`excludeRegex`	string	Reguläres Ausdrucksmuster zum Ausschließen von Seiten
	`userAgent`	string	Kann "any", "desktop" oder "mobile" sein
	`commonProps`	object	Allgemeine Eigenschaften, die für alle Ergebnisse auf dieser Seite gelten
	`delay`	number or boolean	Verzögerung in Millisekunden nach dem Laden der Seite oder boolescher Wert zum Aktivieren/Deaktivieren der Verzögerung

Ergebnisdefinition

Jeder Eintrag im Array results definiert, wie Daten aus einem einzelnen Suchergebnis extrahiert werden sollen:

Erforderlich	Eigenschaft	Typ	Beschreibung
✓	`root`	string or array	Root-Befehl zum Auffinden von Ergebniselementen
✓	`url`	string or array	Eigenschaftsbefehl zum Extrahieren der URL aus dem Ergebnis
	`name`	string	Name der Ergebnisdefinition
	`props`	object	Schlüssel-Wert-Paare, bei denen die Schlüssel Eigenschaftsnamen und die Werte Eigenschaftsbefehle für die Extraktion sind
	`button`	array	Schaltflächenbefehl zum Hinzufügen von Block-Schaltflächen zu den Ergebnissen
	`preserveSpace`	boolean	Legt fest, ob der Layoutbereich blockierter Ergebnisse beibehalten werden soll, um Layoutverschiebungen zu verhindern

Befehle

SERPINFO unterstützt verschiedene Befehle für komplexe Extraktionsszenarien, die in drei Kategorien unterteilt sind:

Root-Befehle

<css-selector> oder [selector, <css-selector>]: Elemente finden, die dem CSS-Selektor entsprechen
[upward, <level>, <root-command>]: Navigieren Sie in der DOM-Struktur um <level> Schritte von jedem Element nach oben, das mit dem Root-Befehl gefunden wurde

Elementbefehle

<css-selector> oder [selector, <css-selector>, <element-command>?]: Element über CSS-Selektor abrufen
[upward, <level>, <element-command>?]: Navigieren Sie in der DOM-Struktur um <level> Schritte nach oben

Hinweis: Wenn <element-command> in einem der oben genannten Befehle weggelassen wird, wird implizit das aktuelle Hauptelement verwendet.

Eigenschaftsbefehle

<css-selector>: Die Eigenschaft textContent (Standard) oder das Attribut href (bei Verwendung in der URL-Extraktion) des Elements abrufen, das dem CSS-Selektor entspricht
[attribute, <name>, <element-command>?]: Attributwert abrufen
[property, <name>, <element-command>?]: Eigenschaftswert abrufen
[const, <value>]: Eine konstante Zeichenkette zurückgeben
[domainToURL, <property-command>]: Domain in eine URL konvertieren
[regexInclude, <pattern>, <property-command>]: Nur einschließen, wenn es mit dem regulären Ausdruck übereinstimmt
[regexExclude, <pattern>, <property-command>]: Ausschließen, wenn es mit dem regulären Ausdruck übereinstimmt
[regexSubstitute, <pattern>, <replacement>, <property-command>]: Durch regulären Ausdruck ersetzen
[or, [<property-command>*], <element-command>?]: Mehrere Befehle nacheinander ausprobieren

Hinweis: Wenn <element-command> in einem der oben genannten Befehle weggelassen wird, wird implizit das aktuelle Hauptelement verwendet.

Schaltflächenbefehle

[icon, <options>?, <element-command>?]: Eine Symbolschaltfläche mit einem bestimmten Stil hinzufügen. Die Optionen umfassen:
- style: Inline-Stil (z. B. "top: 16px; right: 32px; --ub-icon-size: 16px;")
[text, <options>?, <element-command>?]: Eine Text-Schaltfläche mit einer bestimmten Position und einem bestimmten Stil hinzufügen. Die Optionen umfassen:
- position: "beforebegin", "afterbegin", "beforeend" oder "afterend" (Standard: "beforeend")
- style: Inline-Stil (z. B. "color: var(--fg-color); font-size: 14px;")
[inset, <options>?, <element-command>?]: Eine Schaltfläche an einer bestimmten Position innerhalb des Elements hinzufügen. Die Optionen umfassen:
- top: CSS-Länge oder -Prozentsatz
- right: CSS-Länge oder -Prozentsatz
- bottom: CSS-Länge oder -Prozentsatz
- left: CSS-Länge oder -Prozentsatz
- zIndex: z-Index-Wert (Standard: 1)

Hinweis: Wenn <element-command> weggelassen wird, wird das aktuelle Hauptelement verwendet.

Beispiel

Hier ist ein Beispiel für Bing-Bildsuche:

name: Bing
version: 0.1.0
homepage: https://github.com/ublacklist/builtin#readme
license: MIT
lastModified: 2023-04-05T11:11:20Z

pages:
  - name: Images (desktop)
    matches:
      - https://www.bing.com/images/search?*
    userAgent: desktop
    results:
      - root: [upward, 1, ".iuscp"]
        url:
          - regexSubstitute
          - '"purl":"([^"]+)'
          - "\\1"
          - [attribute, "m", ".iusc"]
        props:
          title: [attribute, "title", "li > a"]
        button: [inset, { top: "32px", right: 0 }, ".iuscp"]
    commonProps:
      $site: bing
      $category: images

Abonnement

Ihre SERPINFO veröffentlichen

Sie können Ihre SERPINFO-Definitionen mit anderen teilen, indem Sie Ihre YAML-Datei hosten und einen Abonnement-Link bereitstellen.

Erstellen Sie Ihre SERPINFO-YAML-Datei gemäß dem oben beschriebenen Format
Hosten Sie die Datei unter einer öffentlich zugänglichen URL (z. B. GitHub, Ihre eigene Website)
Teilen Sie den Abonnement-Link mit Benutzern in diesem Format:

https://ublacklist.github.io/serpinfo/subscribe?url=<url-encoded-url>

<url-encoded-url> ist die URL Ihrer gehosteten YAML-Datei, die mit URL-Codierung codiert wurde.

SERPINFO abonnieren

So abonnieren Sie eine SERPINFO-Definition:

Klicken Sie auf einen vom Herausgeber bereitgestellten Abonnement-Link
Die Erweiterung öffnet ihre Optionsseite und fordert Sie auf, das Abonnement hinzuzufügen
Bestätigen Sie, dass Sie SERPINFO zu Ihrer Erweiterung hinzufügen möchten

hinweis

Um Abonnement-Links zu verwenden, müssen Sie diese manuell aktivieren. Gehen Sie zur Optionsseite der Erweiterung und aktivieren Sie "SERPINFO-Abonnement-Links aktivieren".

Dateiformat​

Top-Level-Eigenschaften​

Seitendefinition​

Ergebnisdefinition​

Befehle​

Root-Befehle​

Elementbefehle​

Eigenschaftsbefehle​

Schaltflächenbefehle​

Beispiel​

Abonnement​

Ihre SERPINFO veröffentlichen​

SERPINFO abonnieren​