クライアントの観測可能性

Kotlin

動画統計情報の取り扱い

この手順では、サブスクライバーの動画およびメディアリンクのコールバックを処理し、アプリ内の映像の途切れを診断するとともに、ネットワークの状態を把握します。

監視対象	活用方法
`videoPacketsLost` / `videoBytesReceived`	受信経路に問題があることを確認する（症状：音声の途切れ、フリーズ）
`transport` （ローカルダウンリンク帯域幅）	提案する「接続が弱いようです」ダウンリンクの帯域が逼迫していると思われる場合
`remotePublisherTransport` (リモートアップリンク)	提案する「他の参加者のネットワークが不安定な可能性があります」送信経路に制約があるように見える場合
`networkDegradationSource`	ローカルとリモートのメッセージングのいずれかを選択するか、サポート対応のために両方の帯域幅値を記録してください

1. チャンネル登録者の動画統計情報の取り扱い

実施 SubscriberKit.VideoStatsListener 定期的な動画受信メトリクスを受け取るには：

private val videoStatsListener = SubscriberKit.VideoStatsListener { _, stats ->
    Log.d(TAG, "videoBytesReceived=${stats.videoBytesReceived}")
    Log.d(TAG, "videoPacketsLost=${stats.videoPacketsLost}")
    Log.d(TAG, "videoPacketsReceived=${stats.videoPacketsReceived}")
    Log.d(TAG, "timeStamp=${stats.timeStamp}")

    mainHandler.post {
        latestObservabilityStats = ObservabilityStats.fromVideoStats(
            stats,
            latestMediaLinkSnapshot,
        )
    }
}

コールバックはバックグラウンドスレッドで受信される場合があります。これらのリスナーから Compose や Views を制御する場合は、（前述のように）UI の更新をメインスレッドに投稿してください。

2. メディアリンクの統計情報の管理

実施 SubscriberKit.MediaLinkStatsListener.onMediaLinkStats & SubscriberKit.MediaLinkStatsListener.onNetworkConditionChanged 転送帯域幅および品質低下の原因について。ネットワーク状態のスコアも、 transport そして remotePublisherTransport 各定期サンプルにおいて――参照ネットワーク状況.

private val mediaLinkStatsListener = object : SubscriberKit.MediaLinkStatsListener {
    //
    // Triggers on regular intervals while subscribed
    // Good place for: Overlay numbers, charts, steady telemetry
    //
    override fun onMediaLinkStats(
        subscriber: SubscriberKit,
        mediaLinkStats: SubscriberKit.SubscriberMediaLinkStats,
    ) {
        applyMediaLinkStats(mediaLinkStats)
    }

    //
    // Triggers when the SDK detects a **significant** network condition change
    // Good place for: Toasts, banners, support logs, adaptive UI
    //
    override fun onNetworkConditionChanged(
        subscriber: SubscriberKit,
        mediaLinkStats: SubscriberKit.SubscriberMediaLinkStats,
        reason: String,
    ) {
        Log.d(TAG, "onNetworkConditionChanged reason=$reason")
        applyMediaLinkStats(mediaLinkStats, networkConditionChangeReason = reason)
        handleNetworkDegradation(mediaLinkStats)
    }
}

動画の統計情報とメディアリンクの統計情報は、別々のコールバックで配信されます。このサンプルでは、 MediaLinkSnapshot そして、ビルド時または更新時にそれをマージします ObservabilityStats:

private fun applyMediaLinkStats(
    mediaLinkStats: SubscriberKit.SubscriberMediaLinkStats,
    networkConditionChangeReason: String? = null,
) {
    val localBandwidth = mediaLinkStats.transport?.connectionEstimatedBandwidth
    val remoteBandwidth =
        mediaLinkStats.remotePublisherTransport?.connectionEstimatedBandwidth
    val localCondition = mediaLinkStats.transport?.networkCondition
    val remoteCondition = mediaLinkStats.remotePublisherTransport?.networkCondition
    val conditionReason = mediaLinkStats.transport?.networkConditionReason

    mainHandler.post {
        latestMediaLinkSnapshot = MediaLinkSnapshot(
            localEstimatedBandwidth = localBandwidth,
            remoteEstimatedBandwidth = remoteBandwidth,
            networkDegradationSource = mediaLinkStats.networkDegradationSource,
            localNetworkCondition = localCondition,
            remoteNetworkCondition = remoteCondition,
            lastNetworkConditionChangeReason = networkConditionChangeReason,
        )
        latestObservabilityStats?.let { current ->
            latestObservabilityStats = current.copy(
                localEstimatedBandwidth = localBandwidth,
                remoteEstimatedBandwidth = remoteBandwidth,
                networkDegradationSource = mediaLinkStats.networkDegradationSource,
                localNetworkCondition = localCondition,
                remoteNetworkCondition = remoteCondition,
                lastNetworkConditionChangeReason = networkConditionChangeReason,
            )
        }
        networkConditionChangeReason?.let { changeReason ->
            Log.d(
                TAG,
                "network condition event: $changeReason local=$localCondition remote=$remoteCondition",
            )
        }
    }
}

拡張 MediaLinkSnapshot そして ObservabilityStats 新しいフィールドを追加します（または、次のステップで、条件の整数値をオーバーレイ内のラベルに割り当てます）。

3. ネットワーク状態の悪化を示すイベントへの対応

動画がカクつくときは、 onNetworkConditionChanged ～で発砲する 重要な 変更。以下と組み合わせて使用してください。 networkDegradationSource ユーザー向けの文章を選択するには：

private fun handleNetworkDegradation(
    mediaLinkStats: SubscriberKit.SubscriberMediaLinkStats,
) {
    val localCondition = mediaLinkStats.transport?.networkCondition
        ?: TransportStats.NETWORK_CONDITION_UNKNOWN
    val remoteCondition = mediaLinkStats.remotePublisherTransport?.networkCondition
        ?: TransportStats.NETWORK_CONDITION_UNKNOWN

    when (mediaLinkStats.networkDegradationSource) {
        NetworkDegradationSource.LOCAL -> {
            Log.w(TAG, "Local network degraded (condition=$localCondition)")
            // e.g. show: "Your connection looks weak"
        }
        NetworkDegradationSource.REMOTE -> {
            Log.w(TAG, "Remote publisher network degraded (condition=$remoteCondition)")
            // e.g. show: "The other participant's network may be unstable"
        }
        NetworkDegradationSource.BOTH_OR_UNCLEAR -> {
            Log.w(TAG, "Degradation unclear — local=$localCondition remote=$remoteCondition")
        }
        else -> { /* NetworkDegradationSource.NONE — no action */ }
    }
}

reason で onNetworkConditionChanged そのイベントが発生した理由（たとえば、帯域幅の変化やパケットロスなど）を説明します。これを networkCondition そして networkConditionReason オン transport 分析用。

定義 ObservabilityStats, MediaLinkSnapshotそして fromVideoStats() プロジェクト内で。サンプル ObservabilityStats.kt は出発点です。