Connectivity Report
Tests whether this device and its network can carry a call, and reports why not.
It places a short real test call over the exact route a call takes: HTTPS to your region, the session's signalling connection, and a WebRTC connection to Vonage's media server carrying real microphone audio, whose quality is then measured for a few seconds. Nothing rings, and the test leg is hung up as soon as the test ends.
Because it uses the production route rather than a separate test server, a pass means calls from this device and network will connect, and a failure names the step that broke.
Signature
// Callback version
fun connectivityReport(
options: ConnectivityReportOptions,
callback: (Exception?, ConnectivityReport?) -> Unit
)
// Suspend version
suspend fun connectivityReport(
options: ConnectivityReportOptions = ConnectivityReportOptions()
): ConnectivityReport
fun cancelConnectivityReport()
Parameters
| Property | Type | Default | Description |
|---|---|---|---|
sampleDurationMs | number | 12000 | How long real audio flows once media connects (3000–60000) |
connectTimeoutMs | number | 10000 | How long to wait for media to connect (1000–60000) |
Return Type
A ConnectivityReport. Its JSON form (toJson() on Android, json on iOS, the object itself on JS) is versioned by schemaVersion and is what to send to Vonage support. Absent fields mean "not measured".
| Property | Description |
|---|---|
verdict | pass, warn or fail |
failedAt | The first stage that failed, see below |
issues | Findings, each with a stable code, a severity, the stage and a hint saying what to do |
environment | SDK version, OS, device model, network type (wifi, cellular, +vpn…), configured hosts |
session | Session id, user, connection state, reconnect attempts and the last failure |
https | Reachability of the configured region over HTTPS, with its duration |
microphone | Permission; capturing, whether the microphone delivered audio; heardSound, whether that audio was louder than silence |
media | The test leg id, the media server's address, codec, ICE candidate counts and setup timings |
quality | Min/avg/max round-trip time, jitter, loss (both directions) and estimated MOS, totals, and one sample per second |
Stages
| Stage | Meaning |
|---|---|
https | Vonage could not be reached over HTTPS |
session | There is no usable session |
microphone | The microphone could not be opened, or delivered no audio |
media.offer | The device could not set up its audio |
media.leg | Vonage did not create the test call's audio connection |
media.noAnswer | The media server's answer could not be applied |
media.gathering | The device found no network path to send audio on |
media.checking | Audio could not reach the media server: UDP is blocked |
media.dtls | A path was found but the secure audio handshake failed |
quality | Audio flowed, but with problems: no audio received, dropped, high delay, jitter or loss |
Usage Example
try {
val report = client.connectivityReport()
if (report.verdict != ConnectivityVerdict.Pass) {
println("Failed at: ${report.failedAt}")
report.issues.forEach { println("${it.code}: ${it.hint}") }
}
// The JSON form is what to send to Vonage support.
val forSupport = report.toJson()
}
catch(e: VGError) { /* The test could not run, e.g. a call is in progress */ }
Errors
The callback receives an error only when the test could not run at all. Every check that ran, failures included, is in the report.
| Error Type | Error Code | Description |
|---|---|---|
INTERNAL_ERROR | diagnostics:error:in_progress | A connectivity report is already running |
INTERNAL_ERROR | diagnostics:error:call_in_progress | A call is in progress |
INTERNAL_ERROR | diagnostics:error:cancelled | cancelConnectivityReport was called |
INTERNAL_ERROR | diagnostics:error:interrupted_by_call | A call started during the test |
INTERNAL_ERROR | internal:error:illegal_argument_exception | An option is out of range |
For complete error reference and handling guidelines, see Error Reference.
Notes
- Needs a session. Without one, the report contains the HTTPS and session checks and skips media.
- It uses the microphone like a call does, so it may prompt for microphone permission. Ask the user to speak while it runs: silence never fails the test, but
microphone.heardSoundthen staysfalseand says nothing about whether the microphone picks up sound. - The test leg is a real media leg of about the sample duration, and may be billed as a few seconds of in-app voice.
- Media goes directly to Vonage's media servers over UDP; there is no TCP or TLS relay. When UDP is blocked the report says so: allow outbound UDP 10000–20000 to
216.147.0.0/18and168.100.64.0/18. - No IP address of the device is included. Support can find everything about the test from its
media.legIdandsession.sessionId.