Navigator.registerProtocolHandler() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.registerProtocolHandler(scheme, url)

Beschreibung

Mit navigator.registerProtocolHandler() kann eine Webanwendung dem Browser anbieten, bestimmte URL-Schemata zu verarbeiten. Klickt der Nutzer später z. B. auf einen mailto:-Link, öffnet der Browser statt eines lokalen E-Mail-Programms die registrierte Web-Adresse. Typische Einsatzfälle sind Webmailer (mailto:), Web-Telefonie (tel:, sip:), Kalender (webcal:), Messenger (xmpp:, matrix:) oder eigene App-Schemata mit dem Präfix web+.

Die angegebene Ziel-URL muss den Platzhalter %s enthalten. Der Browser ersetzt ihn beim Aufruf durch die vollständige, URL-kodierte Original-Adresse (z. B. mailto%3Ainfo%40example.com). Die Handler-Seite muss diesen Wert also mit decodeURIComponent() bzw. über URLSearchParams auswerten.

Die Registrierung wird nicht sofort wirksam: Der Browser fragt den Nutzer (meist über ein Symbol in der Adressleiste oder eine Infoleiste) um Erlaubnis. Die Methode liefert keinerlei Rückmeldung darüber, ob der Nutzer zugestimmt hat. Nutzer können registrierte Handler jederzeit in den Browser-Einstellungen entfernen.

Erlaubt sind nur Schemata aus einer festen Sicherheitsliste (u. a. bitcoin, ftp, ftps, geo, im, irc, ircs, magnet, mailto, matrix, mms, news, nntp, openpgp4fpr, sftp, sip, sms, smsto, ssh, tel, urn, webcal, wtai, xmpp) sowie eigene Schemata der Form web+name, wobei name nur aus ASCII-Kleinbuchstaben besteht.

Parameter

Name	Typ	Beschreibung
$scheme Pflicht	string	Das zu behandelnde URL-Schema ohne Doppelpunkt, z. B. `"mailto"` oder `"web+notiz"`. Muss auf der Sicherheitsliste stehen oder mit `web+` beginnen, gefolgt von mindestens einem ASCII-Kleinbuchstaben.
$url Pflicht	string	Ziel-URL des Handlers mit Platzhalter `%s`. Relative Angaben werden gegen die aktuelle Seite aufgelöst. Muss `http(s)` verwenden und denselben Ursprung (Origin) wie die registrierende Seite haben.
$title	string	Veraltet. Früher ein lesbarer Titel für den Nutzerdialog. Wird von aktuellen Browsern ignoriert und sollte weggelassen werden.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Ob der Nutzer die Registrierung bestätigt, ist für die Seite nicht feststellbar.

Beispiele

Webmailer als mailto:-Handler registrieren

// Auf https://mail.example.com ausgeführt
const registerMailHandler = () => {
  if (!('registerProtocolHandler' in navigator)) {
    console.warn('Protokoll-Handler werden in diesem Browser nicht unterstützt.');
    return;
  }
  try {
    navigator.registerProtocolHandler('mailto', '/compose?to=%s');
    console.log('Anfrage gestellt – bitte im Browser bestätigen.');
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
};

document.querySelector('#als-standard')
  .addEventListener('click', registerMailHandler);

Anfrage gestellt – bitte im Browser bestätigen.

Eigenes web+-Schema registrieren

// Links wie <a href="web+notiz:einkaufsliste"> sollen unsere App öffnen
navigator.registerProtocolHandler(
  'web+notiz',
  `${location.origin}/open?uri=%s`
);

Übergebene URL auf der Handler-Seite auswerten

// Auf /open?uri=web%2Bnotiz%3Aeinkaufsliste
const params = new URLSearchParams(location.search);
const raw = params.get('uri'); // URLSearchParams dekodiert bereits

if (raw?.startsWith('web+notiz:')) {
  const noteId = raw.slice('web+notiz:'.length);
  console.log(`Öffne Notiz: ${noteId}`);
} else {
  console.warn('Unerwartetes Schema:', raw);
}

Öffne Notiz: einkaufsliste

Typische Fehler abfangen

const tryRegister = (scheme, url) => {
  try {
    navigator.registerProtocolHandler(scheme, url);
    return 'ok';
  } catch (err) {
    return err.name;
  }
};

console.log(tryRegister('web+app', '/handle'));            // %s fehlt
console.log(tryRegister('meinprotokoll', '/h?u=%s'));      // nicht erlaubt
console.log(tryRegister('web+app', 'https://andere.de/?u=%s')); // fremder Origin

SyntaxError SecurityError SecurityError

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome, Edge, Opera und Firefox (Desktop) unterstützen die Methode, Safari (macOS/iOS) und die meisten mobilen Browser nicht. Immer per 'registerProtocolHandler' in navigator prüfen.
Nur sichere Kontexte: Funktioniert nur über HTTPS (bzw. localhost).
Ausnahmen: SyntaxError, wenn %s in der URL fehlt oder die URL ungültig ist; SecurityError, wenn das Schema nicht erlaubt ist oder die Ziel-URL einen anderen Ursprung hat bzw. kein http(s) verwendet.
Keine Rückmeldung: Ob der Nutzer zustimmt, lässt sich nicht erkennen. Wiederholte Aufrufe können zu wiederholten Aufforderungen führen – am besten nur nach einer Nutzeraktion (Button „Als Standard festlegen“) aufrufen.
Sicherheit: Der Wert aus %s ist nicht vertrauenswürdige Eingabe. Nie ungeprüft per innerHTML ausgeben oder als Weiterleitungsziel verwenden (XSS, offene Weiterleitung) – Schema und Inhalt immer prüfen.
Der dritte Parameter title ist veraltet und wird ignoriert. Das Gegenstück unregisterProtocolHandler() wird kaum unterstützt; Entfernen erfolgt in der Regel über die Browser-Einstellungen.
Für installierte PWAs gibt es alternativ das Manifest-Feld protocol_handlers (derzeit nur Chromium).

Siehe auch

Navigator Navigator.unregisterProtocolHandler() Navigator.setAppBadge() Navigator.taintEnabled() Navigator.clearAppBadge()