Installation (iOS)

The Surfmeter Player SDK for iOS and tvOS ships as a binary XCFramework whose module is called AVPlayerAnalytics. You add it to your app, either with Swift Package Manager or by hand, and then call the API from your own code.

Requirements

• iOS 15.0 or later, or tvOS 15.0 or later
• Xcode 15 or later, with Swift 5.9 or later

The framework is built with library evolution enabled, so it also works with newer Swift compilers than the one it was built with.

Playback is observed through AVFoundation, so the supported streaming formats and codecs are the ones the device itself supports. In practice this means HLS playlists (live or VoD) and progressive MP4, with H.264 and H.265, plus AV1 on the devices that decode it in hardware.

Permissions

The SDK needs no special entitlements. It does make network requests, which is allowed by default.

The default endpoint uses HTTPS. If you point the SDK at an endpoint served over plain HTTP, for instance an on-premise server or a local test setup, you need an App Transport Security exception in your app's Info.plist.

Download

Download the SDK from the links you have been sent, and extract it locally. You will receive two archives:

• AVPlayerAnalytics-$version.zip contains the AVPlayerAnalytics.xcframework folder with the compiled library and its debug symbols
• AVPlayerAnalytics-DemoApp-$version.zip contains the README, the license terms, the API documentation in the docs folder, and the demo app source code as AVFoundationExample.zip

If you integrate with Swift Package Manager, you do not need the first archive, because Swift Package Manager downloads the framework itself.

Integration via Swift Package Manager

This is the recommended way to add the SDK. We host a Swift package at github.com/aveq-research/avplayer-analytics whose manifest points at the compiled framework for each released version. The repository is private, so please ask at support@aveq.info for access to it first.

In Xcode, choose "File" → "Add Package Dependencies", enter the repository URL, and pick the version you want. Xcode downloads the framework and links it for you. Then add the AVPlayerAnalytics library to your app target.

Since the repository is private, Xcode needs a GitHub account that has access to it. Add that account under "Xcode" → "Settings" → "Accounts", using a personal access token with read access to the repository. If you work with SSH keys instead, use git@github.com:aveq-research/avplayer-analytics.git as the URL.

If you manage dependencies in a Package.swift of your own, add it there instead:

dependencies: [
    .package(url: "https://github.com/aveq-research/avplayer-analytics.git", from: "1.4.1")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "AVPlayerAnalytics", package: "avplayer-analytics")
        ]
    )
]

Build machines behind a firewall

The package manifest is a binary target that points at the framework on storage.googleapis.com. A build machine therefore needs to reach both github.com and storage.googleapis.com when it resolves the package. If your build environment does not allow this, add the XCFramework by hand as described below.

Integration of the XCFramework

If you would rather not depend on a remote repository, add the framework by hand. Unzip AVPlayerAnalytics-$version.zip and drag the AVPlayerAnalytics.xcframework folder into your Xcode project.

The XCFramework contains slices for iOS and tvOS, for devices and for the simulator, so the same folder works for all of your targets. It also carries the debug symbols, which lets Xcode symbolicate crash reports that touch the SDK.

Set the framework to Embed & Sign

The SDK is a dynamic framework. Under your target's "General" → "Frameworks, Libraries, and Embedded Content", the framework must be set to "Embed & Sign". If it is only linked and not embedded, the app still runs in the simulator but crashes at launch on a physical device, because the framework is missing from the app bundle.

Verifying the Integration

Import the module and print the version to confirm everything is wired up:

import AVPlayerAnalytics

print("Surfmeter Player SDK \(Version.current)")

Once the SDK is part of your project, you can start using it.

API Documentation

The docs folder of the demo app archive holds the API reference for every public type in the SDK, generated with DocC. There are two ways to read it:

• Double-click docs/AVPlayerAnalytics.doccarchive to open it in Xcode, where it appears alongside Apple's own framework documentation.
• Run docs/serve-docs.sh to read it in your browser. The script needs Python 3 and starts a local web server.

Note

Opening docs/html/index.html directly does not work. The browser will not load the documentation data from the file system, so the page stays empty. Use one of the two ways above.

Updating the SDK

If you integrated via Swift Package Manager, choose "File" → "Packages" → "Update to Latest Package Versions" in Xcode, or bump the version requirement in your Package.swift.

If you integrated the XCFramework by hand, download the new archive and replace the AVPlayerAnalytics.xcframework folder with the new one.

The changelog lists what changed in each version.

Logging

The SDK logs through OSLog, using your app's bundle identifier as the subsystem. In the Console app, filter on that subsystem and on the Main, SurfmeterAnalytics, AVPlayerObserver, ClientAnalyticsRemoteApi or StateMachine categories to follow what the SDK is doing.

If the SDK logs create too much noise in your own logs, you can turn them off, or send them to a subsystem of your own:

import AVPlayerAnalytics

LoggingConfiguration.shared.loggingEnabled = false
LoggingConfiguration.shared.subsystem = "info.example.myapp.surfmeter"

Set this in your app's initialization code, before you create the first analytics instance.