Preflight API

The Preflight API is included with the Twilio Video JavaScript SDK in versions 2.16.0 and above. Versions 2.16.0 through 2.19.1 of the JavaScript SDK contain beta version of the Preflight API. Version 2.20.0 and above of the JavaScript SDK contain the generally available Preflight API, which is no longer in beta.

You can include the JavaScript SDK in your application either by installing it with Node Package Manager (npm) or using the Twilio CDN.

See the list of supported browsers here.

Install the Video JavaScript SDK using npm:

npm install --save twilio-video

Then, you can start using the Preflight API in your application (note that the Preflight API is under the name runPreflight):

const { runPreflight } = require('twilio-video');

You can also copy twilio-video.min.js from the twilio-video/dist folder after npm installing it and include it directly in your web app using a <script> tag.

<script src="https://my-server-path/twilio-video.min.js"></script>

Using this method, you can access the PreflightTest API like so:

const runPreflight = Twilio.Video.runPreflight;

You can also include the JavaScript SDK in your application from Twilio's CDN:

<script src="https://sdk.twilio.com/js/video/releases/2.20.0/twilio-video.min.js"></script>

Using the CDN, the JavaScript SDK will set a browser global that you can use to reference the Preflight API:

const runPreflight = Twilio.Video.runPreflight;

Below is an example of how to use the Preflight API to start a diagnostic connectivity test and handle events during the test.

1
// import the Preflight API, which is called `runPreflight`,
2
// from the Twilio Video JavaScript SDK
3
const { runPreflight } = require('twilio-video');
4

5
// if you are using the Video JavaScript SDK via the Twilio CDN or
6
// a script tag, you would reference the Preflight API this way:
7
// const runPreflight = Twilio.Video.runPreflight;
8

9
// this assumes you have a function called getAccessToken
10
// to retrieve an Access Token from your server
11
const token = getAccessToken();
12

13
// run a preflight test, passing in an Access Token with
14
// a VideoGrant
15
const preflightTest = runPreflight(token);
16

17
// handle preflight test events
18

19
// while the test is in progress, the progress event fires
20
// whenever a particular PreflightProgress step completes
21
preflightTest.on('progress', (progress) => {
22
  console.log('preflight progress:', progress);
23
});
24

25
// if the test failed, the failed event fires and returns the error
26
// along with the partial test results it was able to collect
27
preflightTest.on('failed', (error, report) => {
28
  console.error('preflight error:', error);
29
  console.log('Received partial report:', report);
30
});
31

32
// if the test completed without error, the completed event fires
33
// and returns the preflight test report
34
preflightTest.on('completed', (report) => {
35
  console.log("Test completed in " + report.testTiming.duration + " milliseconds.");
36
  console.log(" It took " + report.networkTiming.connect?.duration + " milliseconds to connect");
37
  console.log(" It took " + report.networkTiming.media?.duration + " milliseconds to receive media");
38
});

To start a diagnostic test with the Preflight API, call the runPreflight() method and pass in an Access Token with a VideoGrant, which allows you to set up test connections to Twilio's servers.

You can optionally pass in other PreflightOptionswhen you run the test. The options include setting your preferred signaling region within the Twilio cloud (region; default is gll) and the amount of time to run the test (duration; the default is 10000 ms, or 10 seconds).

The Access Token you pass to the runPreflight must contain a VideoGrant.

Because the Preflight API is connecting to a test Video Room that the Preflight API sets up, any value you pass in for the room and identity fields in the VideoGrant will be ignored during the preflight test. The Access Token you use does require an identity field, but this identity can be any value for the purpose of the test.

After you start running the preflight test with the runPreflight method, the test can generate three types of events. The code example above demonstrates how to listen for each event type.

• progress: The test is in progress and a PreflightProgress step in the test completed. This event passes the specific PreflightProgress step that completed.
• failed: The test failed with an error. This event passes back the error and any partially generated test results.
• completed: The test completed successfully and you can review the results. This event passes back the completed test report.

While the Preflight Test is in progress, it will emit ProgressEvents indicating it completed specific connectivity checks. You can use these events to track the test progress and provide additional feedback to end users about their connections.

The completed event will pass back a report containing the results from the successful test. The report will contain the following fields:

You can stop an in-progress test with the stop() method. This will stop the test and emit a failed event, along wtih partial test results that completed up to the point that the test stopped.

Twilio offers an open-source Video Diagnostics Application that is built using the Prelight API and the RTC Diagnostics SDK. You can deploy and explore this application to see the different functionality of these diagnostic APIs in action. The application tests participants' device and software setup, connectivity with the Twilio Cloud, and network performance. It provides users feedback about their network quality and device setup, and also includes recommendations for improving their video call quality.