Skip to content

Overview (iOS)

To use the Surfmeter Mobile Quality SDK on iOS, you generally need to perform two main steps:

  1. Register your client. This is a one-time setup process using your license key. A test cannot be built until the server has confirmed the device.
  2. Instantiate and run a quality test. Choose AVPlayer, web, or a supported web-based video service, configure its builder, then start it.

All three test types follow the same shape. You create a builder, set the options you need, attach a result listener, call build() and then start(). The test runs on the main thread, reports its progress through the listener, and delivers one final callback with either the measurement report or an error message. Everything is computed on the device, and the result is uploaded to your Surfmeter server after registration.

An AVPlayerQualityTest can continue after the host app enters the background when the app is configured for background media playback and opts in through setAllowsBackgroundPlayback(true). iOS does not provide the service-based background scheduling available on Android, and the WebKit-based video and web tests still require the app to remain visible. See Background Execution for the host requirements and lifecycle.

While a test runs, the SDK records changes to the available connection details and can record precise location updates. The host app should request and explain location access before the test. A missing or approximate-only location never fails the test; it produces an empty geolocation_trace. See Measurement Context and Privacy for the integration and disclosure requirements.

This section provides links to detailed explanations for each of these steps and test types.

Demo App

A demo app is provided with the SDK to illustrate its usage. You can find it by unzipping the QualitySDKExample.zip file. It is a SwiftUI app with four tabs:

  • a video test tab, which runs an AVPlayerQualityTest against a configurable stream URL and can opt in to background playback
  • a web test tab, which runs a WebQualityTest against a configurable page URL
  • a Video tab, which runs a VideoQualityTest against YouTube or a public Netflix Tudum trailer
  • a results tab, which lists every finished report, shows the individual values and raw JSON, and reports whether a manual upload succeeded or failed

The demo app reads the server endpoint and registration key from its build settings rather than from source, so that neither ends up in a build by accident. Copy Config/Local.xcconfig.example to Config/Local.xcconfig and put your values in there. Without them the app cannot register, and no test will run.

The demo also explains why professional measurements benefit from precise location. It offers the system permission action without blocking tests when location remains unavailable.

You can take the views from the demo into your existing application, or start a new app from it. Ensure that you have correctly set up the SDK as outlined in the installation instructions. See the README in the archive for how to swap the local package reference for the real SDK.

If you need more information, refer to the specific pages for more detailed information on each aspect:

Every class and method is also described in the API documentation that ships with the SDK.