Remote Audio Data is a framework for reporting the listenership of podcasts in iOS apps.

If you want to view the RAD specification in more detail, please visit this page.

Add RAD dependency in your Cartfile

github "npr/RAD-iOS"

and follow the general flow to add the RAD and, its dependency, Reachability frameworks into your project.

Add RAD pod in your Podfile and execute pod update using the command line in your project directory.

Example:

target 'TargetName' do
  # Comment the next line if you're not using Swift and don't want to use dynamic frameworks
  use_frameworks!

  # Pods for TargetName
  pod "RAD"
end

The RAD framework consists of a single class Analytics which provides support to start collecting data from an AVPlayer and send the data to Analytics servers.

Import the Swift module in the files which is used

import RAD

Within your business model create an instance of Analytics.

let analytics = Analytics()

Or you use a singleton if it is appropriate:

static let RADAnalytics = Analytics()

The Analytics object has a configuration property. By using this constructor, a default Configuration is used. To see default values of Configuration, you can check the Analytics class.

A custom configuration may be passed to the Analytics instance via constructor.

let configuration = Configuration(
            submissionTimeInterval: TimeInterval.minutes(30), // how much time to wait until the stored events in the local storage are sent to analyics servers
            batchSize: 10, // how many events are send per network request
            expirationTimeInterval: DateComponents(day: 2), // how much time is an event valid
            sessionExpirationTimeInterval: TimeInterval.hours(24), // how much time is a session identifier active
            requestHeaderFields: [
               "UserAgent": "iPhone/iOS",
               "MyCustomKey": "CustomValue"] // header fields which will be added on each network request
)
let analytics = Analytics(configuration: configuration)

To start recording data, pass an instance of AVPlayer to the instance of Analytics. Upon creating the player it is required to no initialize with any item, otherwise that item will not be analyzed.

let player = AVPlayer(playerItem: nil) // intialize the player
analytics.observePlayer(player) // start observing
player.replaceCurrentItem(with: playerItem) // change current item

To provide support for sending data while application is in background, it is required to enable Background Fetch and override application(_:performFetchWithCompletionHandler:). Example:

func application(
     _ application: UIApplication,
     performFetchWithCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
     analytics.performBackgroundFetch(completion: completionHandler)
}

Sending data to the analytics servers may be stopped or started at anytime. By default, data is sent to the servers when the Analytics object is created.

You can start and stop the data send using the following methods:

analytics.stopSendingData() // the next data send schedule is cancelled and data is not send to servers anymore
analytics.startSendingData() // schedule a point in time when to send data to servers based on configuration

Analytics provides a debug interface (AnalyticsDebuggable) which can be used to check if listening ranges are created or if network requests are performed.

To register for listening ranges, your class should implement ListeningObserver and register using to debugger:

analytics.debugger.addListeningObserver(yourObject)

To register for network requests, your class should implement NetworkObserver and register using to debugger:

analytics.debugger.addNetworkObserver(yourObject)

Demo application used this API and created 2 reusable unit tests that checks if integration of RAD framework is successful.

A demo project is available. Before first run, it is required to checkout its dependencies using Carthage

carthage update --platform iOS --cache-builds --no-use-binaries