WebRTC: guida alla migrazione con getStats() precedente

Henrik Boström

L'API WebRTC getStats() precedente verrà rimossa in Chrome 117, pertanto le app che la utilizzano dovranno eseguire la migrazione all'API standard. Questo articolo spiega come eseguire la migrazione del codice e cosa fare se hai bisogno di più tempo per apportare questa modifica.

Storicamente esistono due versioni concorrenti dell'API WebRTC getStats(). L'API legacy getStats(), che precede il processo di standardizzazione e utilizza un argomento di callback, e l'API standardizzata e ampiamente supportata che restituisce una promessa.

L'API standard è più ricca di funzionalità e presenta metriche ben definite documentate pubblicamente nella specifica W3C Identifiers for WebRTC's Statistics API. La specifica include le descrizioni di ogni metrica elencata in questa guida e molte altre.

A partire da Chrome 117, l'API getStats() precedente genererà un'eccezione nel canale di rilascio stabile (la generazione delle eccezioni verrà implementata gradualmente). Segui questa guida per semplificare la transizione all'API standard.

Tipi di statistiche precedenti e standard

L'elenco completo dei tipi di statistiche standard è disponibile nell'enumerazione RTCStatsType nella specifica. Include la definizione del dizionario delle statistiche che descrive le metriche raccolte per ogni tipo.

Tutti gli oggetti statistica hanno un attributo ID che identifica in modo univoco l'oggetto sottostante in più chiamate getStats(). Lo stesso oggetto avrà lo stesso ID ogni volta che viene chiamato il metodo. Questo è utile per calcolare il tasso di variazione delle metriche (c'è un esempio nella sezione successiva). Gli ID formano anche relazioni di riferimenti. Ad esempio, l'oggetto statistiche outbound-rtp fa riferimento all'oggetto statistiche media-source associato tramite l'attributo outbound-rtp.mediaSourceId. Se tracci tutte le relazioni di ...Id, viene visualizzato un grafico.

L'API legacy dispone dei seguenti tipi di statistiche, corrispondenti ai tipi standard come segue:

Mappatura delle metriche da legacy a standard

Questa mappatura è pensata per aiutare gli sviluppatori a capire quale metrica precedente corrisponde a una metrica standard, ma tieni presente che la metrica corrispondente potrebbe utilizzare unità diverse o essere espressa come contatore totale anziché come valore istantaneo. Fai riferimento alle specifiche per le definizioni delle metriche.
L'API standard preferisce esporre i contatori totali piuttosto che le tariffe. Ciò significa che per ottenere la velocità corrispondente (ad esempio, la velocità in bit) come nell'API precedente, l'app deve calcolare la velocità media facendo il delta tra due chiamate getStats(). Ad esempio:

// Periodically (e.g. every second or every 10 seconds)...
const currReport = await pc.getStats();
// Calculate bitrate since the last getStats() call.
// Handling of undefined is omitted for clarity.
const currOutboundRtp = currReport.values().find(s => s.type == 'outbound-rtp');
const prevOutboundRtp = prevReport.get(currOutboundRtp.id);
const deltaBits = (currOutboundRtp.bytesSent - prevOutboundRtp.bytesSent) * 8;
const deltaSeconds = (currOutboundRtp.timestamp - prevOutboundRtp.timestamp) / 1000;
logBitrateMeasurement(deltaBits / deltaSeconds);
// Remember the report for next time.
prevReport = currReport;

Dover calcolare personalmente tariffe e medie in questo modo può sembrare un passaggio aggiuntivo gravoso, ma ha l'aspetto positivo di consentirti di ottenere le medie sull'intervallo di tempo desiderato. Chiamare l'API standard meno spesso di quanto avresti dovuto fare con l'API legacy offre alcuni vantaggi in termini di prestazioni.

L'API standard è sensibile alla simulcast

Se utilizzi simulcast, potresti aver notato che l'API legacy segnala solo un singolo SSRC anche quando utilizzi questa modalità per inviare (ad esempio) tre stream RTP su tre SSRC separati.

L'API standard non condivide questa limitazione e restituisce tre oggetti statistiche outbound-rtp, uno per ciascuno degli SSRC. Ciò significa che puoi analizzare ogni singolo stream RTP, ma significa anche che per ottenere la velocità in bit totale di tutti gli stream di invio RTP dovrai aggregarli personalmente.

Gli stream SVC o RTP con più livelli spaziali configurati tramite l'API scalabilityMode vengono invece visualizzati come un singolo outbound-rtp perché vengono inviati tramite un singolo SSRC.

Se hai bisogno di più tempo per la migrazione

Quando l'API precedente viene rimossa in Chrome 117, il suo utilizzo genera un'eccezione. Se non riesci a eseguire la migrazione del codice in tempo, la prova dell'origine per l'API getStats() basata su callback RTCPeerConnection offre più tempo ai siti web registrati per eseguire la migrazione. Con un token di prova dell'origine, l'API getStats() precedente potrebbe continuare a essere utilizzata fino a Chrome 121.