Navigator.unregisterProtocolHandler() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.unregisterProtocolHandler(scheme, url)

Beschreibung

navigator.unregisterProtocolHandler() ist das Gegenstück zu navigator.registerProtocolHandler(). Damit entfernt eine Webanwendung eine Verknüpfung, über die der Browser Links mit einem bestimmten Schema (etwa mailto:, irc: oder ein eigenes web+kalender:) an eine URL dieser Anwendung weitergibt.

Typische Einsatzfälle sind eine Einstellungsseite, auf der Nutzer die Verknüpfung „Diese App als Standard für E-Mail-Links verwenden“ wieder abschalten können, oder das Aufräumen beim Abmelden bzw. Löschen eines Kontos.

Wichtig: scheme und url müssen genau mit den Werten übereinstimmen, die bei der Registrierung verwendet wurden – einschließlich des Platzhalters %s. Eine Website kann nur Handler entfernen, die zu ihrem eigenen Ursprung gehören. Stimmt keine Registrierung überein, passiert einfach nichts – es gibt auch keinen Fehler.

Die Methode funktioniert nur in einem sicheren Kontext (HTTPS). Sie gibt synchron undefined zurück und meldet nicht, ob tatsächlich ein Handler entfernt wurde.

Parameter

Name	Typ	Default	Beschreibung
$scheme Pflicht	string		Das URL-Schema ohne Doppelpunkt, z. B. `"mailto"`, `"magnet"` oder ein eigenes Schema mit dem Präfix `"web+"` (etwa `"web+notiz"`). Es muss ein erlaubtes Schema sein.
$url Pflicht	string		Die Handler-URL genau so, wie sie registriert wurde, mit dem Platzhalter `%s`. Relative URLs werden relativ zur Dokument-URL aufgelöst. Die URL muss denselben Ursprung wie die aufrufende Seite haben.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Ob wirklich ein Handler entfernt wurde, lässt sich nicht erkennen.

Beispiele

Registrierten mailto-Handler wieder entfernen

// Genau die URL verwenden, die bei der Registrierung übergeben wurde
const HANDLER_URL = 'https://mail.example.com/compose?to=%s';

if ('unregisterProtocolHandler' in navigator) {
  navigator.unregisterProtocolHandler('mailto', HANDLER_URL);
  console.log('mailto-Handler entfernt');
} else {
  console.warn('unregisterProtocolHandler wird nicht unterstützt');
}

mailto-Handler entfernt

Umschalter auf einer Einstellungsseite

const SCHEME = 'web+notiz';
const URL_TEMPLATE = `${location.origin}/notiz/oeffnen?uri=%s`;

const checkbox = document.querySelector('#als-standard');

checkbox.addEventListener('change', () => {
  try {
    if (checkbox.checked) {
      navigator.registerProtocolHandler(SCHEME, URL_TEMPLATE);
    } else {
      navigator.unregisterProtocolHandler(SCHEME, URL_TEMPLATE);
    }
    localStorage.setItem('notizHandler', String(checkbox.checked));
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
    checkbox.checked = !checkbox.checked; // Zustand zurücksetzen
  }
});

Fehler bei falscher URL abfangen

try {
  // Kein %s-Platzhalter → SyntaxError
  navigator.unregisterProtocolHandler('web+notiz', '/notiz/oeffnen');
} catch (err) {
  console.log(err.name);
}

try {
  // Fremder Ursprung → SecurityError
  navigator.unregisterProtocolHandler('web+notiz', 'https://andere-seite.example/?u=%s');
} catch (err) {
  console.log(err.name);
}

SyntaxError SecurityError

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Chromium-Browser (Chrome, Edge, Opera) unterstützen die Methode. Firefox hat zwar registerProtocolHandler(), aber kein unregisterProtocolHandler(). Safari unterstützt beides nicht. Prüfe deshalb vorher mit 'unregisterProtocolHandler' in navigator. Wo die Methode fehlt, müssen Nutzer den Handler in den Browser-Einstellungen selbst entfernen.
Exakte Übereinstimmung: Schon eine kleine Abweichung in der URL (anderer Pfad, anderer Query-Parameter, fehlender Schrägstrich) führt dazu, dass nichts entfernt wird – und zwar ohne Fehlermeldung. Am besten legst du Schema und URL als gemeinsame Konstante für beide Aufrufe an.
Ausnahmen: Ein SecurityError kommt, wenn das Schema nicht erlaubt ist (weder in der Liste der sicheren Schemata noch mit web+-Präfix plus Kleinbuchstaben) oder wenn die URL einen anderen Ursprung hat bzw. nicht http(s) ist. Ein SyntaxError kommt, wenn der Platzhalter %s fehlt.
Sicherer Kontext: Die Methode steht nur über HTTPS (oder localhost) zur Verfügung.
Es gibt keine API, mit der man abfragen kann, ob ein Handler registriert ist. Den Zustand solltest du deshalb selbst speichern, z. B. in localStorage.

Siehe auch

Navigator.registerProtocolHandler() Navigator isSecureContext Navigator.setAppBadge() PerformanceSoftNavigation.getLargestInteractionContentfulPaint()