RTCIceCandidateStats.localCandidateId — Eigenschaft · JavaScript-Referenz

Signatur

RTCIceCandidatePairStats.localCandidateId

Beschreibung

Die Eigenschaft localCandidateId gehört zu den Statistiken eines ICE-Kandidatenpaars (RTCIceCandidatePairStats, type === "candidate-pair"). Obwohl sie oft im Zusammenhang mit RTCIceCandidateStats genannt wird, steht sie nicht auf dem Kandidatenobjekt selbst. Sie enthält die id des Statistikeintrags vom Typ "local-candidate", der die lokale Seite dieses Paars beschreibt.

Ein RTCStatsReport von RTCPeerConnection.getStats() ist eine Map. Mit report.get(pair.localCandidateId) kommst du deshalb direkt an die Details des lokalen Kandidaten, also an address, port, protocol und candidateType (host, srflx, prflx oder relay). Das Gegenstück für die Gegenseite ist remoteCandidateId.

In der Praxis brauchst du die Eigenschaft vor allem zur Diagnose von Verbindungen. Damit prüfst du zum Beispiel, ob gerade ein TURN-Relay genutzt wird, ob die Verbindung über UDP oder TCP läuft oder welche Netzwerkschnittstelle aktiv ist. Das gerade genutzte Paar findest du über RTCTransportStats.selectedCandidatePairId.

Rückgabewert

Typ

string

Beschreibung

Die id des RTCIceCandidateStats-Eintrags (type: "local-candidate") im selben RTCStatsReport. Nur lesbar.

Beispiele

Lokalen Kandidaten des aktiven Paars ermitteln

// pc ist eine verbundene RTCPeerConnection
const getActiveLocalCandidate = async (pc) => {
  const report = await pc.getStats();
  let transport;
  report.forEach((s) => {
    if (s.type === 'transport') transport = s;
  });
  if (!transport?.selectedCandidatePairId) return null;

  const pair = report.get(transport.selectedCandidatePairId);
  const local = report.get(pair.localCandidateId);
  return {
    typ: local.candidateType,
    protokoll: local.protocol,
    adresse: `${local.address ?? local.ip}:${local.port}`
  };
};

console.log(await getActiveLocalCandidate(pc));

{ typ: 'srflx', protokoll: 'udp', adresse: '203.0.113.7:54321' }

Alle Kandidatenpaare mit lokaler und entfernter Seite auflisten

const listPairs = async (pc) => {
  const report = await pc.getStats();
  for (const stat of report.values()) {
    if (stat.type !== 'candidate-pair') continue;
    const local = report.get(stat.localCandidateId);
    const remote = report.get(stat.remoteCandidateId);
    console.log(
      `${stat.state.padEnd(10)} ${local?.candidateType} -> ${remote?.candidateType}` +
      (stat.nominated ? ' (nominiert)' : '')
    );
  }
};

await listPairs(pc);

succeeded host -> host (nominiert) failed relay -> srflx

Prüfen, ob die Verbindung über TURN läuft

const usesTurnRelay = async (pc) => {
  const report = await pc.getStats();
  const pair = [...report.values()].find(
    (s) => s.type === 'candidate-pair' && s.nominated && s.state === 'succeeded'
  );
  if (!pair) return false;
  return report.get(pair.localCandidateId)?.candidateType === 'relay';
};

if (await usesTurnRelay(pc)) {
  console.warn('Medien laufen über TURN – höhere Latenz möglich.');
}

Medien laufen über TURN – höhere Latenz möglich.

// Wichtig · Fallstricke

Richtiges Objekt: localCandidateId gibt es nur bei Statistiken vom Typ "candidate-pair", nicht bei "local-candidate"- oder "remote-candidate"-Einträgen.
IDs gelten nur im selben Bericht: Löse die ID immer im selben RTCStatsReport auf, aus dem das Paar stammt. Zwischen verschiedenen getStats()-Aufrufen ist sie nicht garantiert stabil.
Aktives Paar finden: Die Standard-Methode ist RTCTransportStats.selectedCandidatePairId. Die ältere, nicht standardisierte Eigenschaft selected auf dem Paar gab es nur in Firefox. Verlass dich nicht darauf. Als Notlösung taugt nominated && state === "succeeded".
Datenschutz: Die Browser verbergen lokale IP-Adressen teilweise, zum Beispiel über mDNS-Namen wie xyz.local. Außerdem hieß address früher ip. Deshalb können diese Felder leer sein oder anders heißen.
Der Eintrag, auf den die ID verweist, kann fehlen, etwa nach einem ICE-Restart. Prüfe das Ergebnis von report.get() deshalb vor dem Zugriff.

Siehe auch

RTCIceCandidatePairStats.remoteCandidateId RTCIceCandidateStats RTCIceCandidatePairStats RTCPeerConnection.getStats() RTCStatsReport MediaTrackSupportedConstraints.echoCancellation RTCIceCandidateStats.priority