HTMLAreaElement.ping — Eigenschaft · JavaScript-Referenz

Signatur

HTMLAreaElement.ping

Beschreibung

Die Eigenschaft ping der Schnittstelle HTMLAreaElement spiegelt das HTML-Attribut ping eines <area>-Elements wider, also eines anklickbaren Bereichs in einer Image-Map. Der Wert ist ein String mit einer oder mehreren URLs, die durch Leerzeichen getrennt sind.

Folgt der Nutzer dem Link des Bereichs (href), schickt der Browser im Hintergrund an jede dieser URLs eine POST-Anfrage mit dem Rumpf PING und dem Content-Type text/ping. Zusätzlich werden die Header Ping-From und Ping-To mitgesendet. So lassen sich Klicks auf ausgehende Links erfassen (Hyperlink Auditing), ohne auf JavaScript-Umleitungen oder Tracking-Weiterleitungen zurückgreifen zu müssen. Die Navigation selbst wird dadurch nicht verzögert.

Die Eigenschaft lässt sich lesen und schreiben. Wenn du einen neuen Wert zuweist, wird das Attribut im DOM sofort geändert. Ist kein Attribut gesetzt, liefert die Eigenschaft einen leeren String. Das Parsen der URL-Liste übernimmt der Browser erst beim Klick. Relative URLs werden dabei gegen die Basis-URL des Dokuments aufgelöst.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des ping-Attributs als String mit durch Leerzeichen getrennten URLs, oder "", wenn das Attribut fehlt. Weist du einen Wert zu, wird er in einen String umgewandelt und als Attribut gesetzt.

Beispiele

Ping-URLs eines Map-Bereichs auslesen

// HTML:
// <map name="karte">
//   <area id="nord" shape="rect" coords="0,0,100,50"
//         href="https://example.com/nord"
//         ping="/stats/klick https://tracker.example.net/p" alt="Nord">
// </map>
const area = document.getElementById('nord');
console.log(area.ping);

// In ein Array aufteilen
const urls = area.ping.split(/\s+/).filter(Boolean);
console.log(urls.length);

/stats/klick https://tracker.example.net/p 2

Ping-Tracking für alle Bereiche einer Image-Map setzen

const map = document.querySelector('map[name="karte"]');

for (const area of map.querySelectorAll('area[href]')) {
  // Eine eigene Statistik-URL pro Bereich
  const id = encodeURIComponent(area.id || area.alt);
  area.ping = `/api/klicks?bereich=${id}`;
}

console.log(map.querySelector('area').getAttribute('ping'));

/api/klicks?bereich=nord

Unterstützung prüfen und Fallback mit sendBeacon

const area = document.querySelector('area#nord');
const pingSupported = 'ping' in HTMLAreaElement.prototype;

if (pingSupported) {
  area.ping = '/stats/klick';
} else {
  area.addEventListener('click', () => {
    navigator.sendBeacon('/stats/klick', JSON.stringify({ ziel: area.href }));
  });
}
console.log(pingSupported);

true (in Chromium/Safari)

Ping-Attribut wieder entfernen

const area = document.querySelector('area#nord');
area.ping = '';          // leert den Wert, das Attribut bleibt aber bestehen
area.removeAttribute('ping'); // entfernt es vollständig
console.log(area.ping === '', area.hasAttribute('ping'));

true false

// Wichtig · Fallstricke

Browser-Unterstützung: In Chrome, Edge, Opera und Safari werden Pings tatsächlich versendet. In Firefox gibt es die Eigenschaft zwar, Pings sind dort aber standardmäßig abgeschaltet (browser.send_pings). Auch einige Datenschutz-Browser und Erweiterungen blockieren sie. Verlasse dich also nicht darauf, dass jeder Klick erfasst wird.
Nur bei echter Navigation: Ein Ping wird nur versendet, wenn das <area> ein href hat und der Nutzer dem Link tatsächlich folgt. Ruft ein Klick-Handler preventDefault() auf, wird kein Ping gesendet.
Datenschutz: ping ist ein Tracking-Mechanismus. Nach DSGVO ist er in der Regel einwilligungspflichtig, sobald personenbezogene Daten oder Daten von Drittanbietern betroffen sind.
Cross-Origin: Pings an fremde Origins sind erlaubt. Je nach Referrer-Policy werden aber weniger Header mitgesendet (Ping-From kann fehlen). Der Server muss auf POST mit Content-Type: text/ping antworten können. CORS-Antwortheader sind dafür nicht nötig.
Nur http(s): URLs mit anderen Schemata werden ignoriert. Der String selbst wird beim Setzen nicht geprüft, Tippfehler bleiben also unbemerkt.
Die gleichnamige Eigenschaft gibt es auch bei HTMLAnchorElement. Sie verhält sich dort genauso.

Siehe auch

FileSystemHandle.kind HTMLAreaElement.host HTMLAreaElement.port HTMLAreaElement.alt HTMLAreaElement.hash