Audioburst Mobile Library

Introduction

AudioburstMobileLibrary is a multi platform library that allows convenient access to the Audioburst’s Content APIs. Playlists can be accessed, selected by users and additional information can be requested about the playlist.

For further information about the flow and objects used by the library please refer to our wiki page

Features

AudioburstMobileLibrary offers a simple API that lets you:

Get all available playlists
Get information about specific playlists, including lists of Burst
Handle sending required events to the API without any effort.

Prerequisites

Audioburst API key

The library requires an application key that can be obtained via Audioburst Publishers.

Get Started - Android

This guide is a quick walkthrough to add AudioburstMobileLibrary to an Android app. We recommend Android Studio as the development environment for building an app with the AudioburstMobileLibrary.

Add AudioburstMobileLibrary to your app

Step 1. Add AudioburstMobileLibrary dependency

Add AudioburstMobileLibrary Android SDK to your project. To do this, add the following dependency in your app level build.gradle file:

implementation 'com.audioburst:mobile-library:{latest-version}'

The library is built in Kotlin language and is using Coroutines, so to be able to support it you need to add the following configurations to your android script in the app level build.config file:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

In the event you are getting a "Duplicate class" on Kotlin Coroutines dependencies, you need to exclude those from the AudioburstPlayer library in the following way:

implementation ("com.audioburst:mobile-library:{latest-version}") {
    exclude group: "org.jetbrains.kotlinx", module: "kotlinx-coroutines-core-jvm"
}

Step 2. Initialize `AudioburstLibrary` object

val audioburstLibrary: AudioburstLibrary = AudioburstLibrary("YOUR_API_KEY_HERE")

You can use this class by instantiating its instance every time you need this or as a singleton.

Legacy support

Use the library's 'setAudioburstUserID' function to keep a pre-existing Audioburst API User ID.

audioburstLibrary.setAudioburstUserID("EXISTING_AUDIOBURST_API_USER_ID")
    .onData { isSuccess ->
        // If isSuccess is true, then you are ready to use existing Audioburst API User ID
    }
    .onError { error -> 
        // Handle error 
    }

Step 3. Request Audioburst content

All the functions below are suspending, which means that you need to call them using a CoroutineScope. Additionally, they return the Result object which can be either Data or Error. The library offers a few handy extension functions that make it easier to work with this type. Check the Result class to learn more about it.

Get all available playlists

audioburstLibrary.getPlaylists()
    .onData { playlists ->
        // Display available playlists
    }
    .onError { error -> 
        // Handle error
    }

Get playlist information

audioburstLibrary.getPlaylist(playlistItem)
    .onData { playlist ->
        // Build your playback queue by using list of Bursts
    }
    .onError { error -> 
        // Handle error
    }

Get advertisement url

You can also play advertisements before playlist items (bursts.) To do so, check if a specific Burst has an ad by calling Burst.isAdAvailable. If an ad is available then before playing the Burst content call getAdUrl which allows a Burst to be played with an ad.

audioburstLibrary.getAdUrl(burst)
    .onData { adUrl ->
        // Play ad
    }
    .onError { error -> 
        // Handle error
    }

Manage user preferences

The library also includes the capability to manage (get and update) user preferences.

audioburstLibrary.getUserPreferences()
    .onData { userPreferences ->
        // Use user preferences
    }
    .onError { error -> 
        // Handle error
    }

audioburstLibrary.setUserPreferences(userPreferences)
    .onData { userPreferences ->
        // Use updated user preferences
    }
    .onError { error -> 
        // Handle error
    }

Get Personalized Playlist using async

The library includes the capability to get a personalized playlist constructed according to a user’s preferences. In order to shorten the loading time of the personalized playlist, the library exposes the ability to "subscribe" to ongoing changes in the playlist. Subscribing enables notifications every time new Bursts are added to the playlist and the ability to check if the playlist is ready.

audioburstLibrary
    .getPersonalPlaylist()
    .collect { result -> 
        result
            .onData { pendingPlaylist -> 
                if (pendingPlaylist.isReady) {
                    // Your playlist is ready
                } else {
                    // Your playlist is still being prepared
                }
            }
            .onError { error -> 
                // Handle error
            } 
    }

Pass recorded PCM file

AudioburstLibrary is able to process raw audio files that contain a recorded request of what should be played. You can record a voice command stating what you would like to listen to and then upload it to your device and use AudioburstLibrary to get bursts on this topic.

audioburstLibrary.getPlaylist(byteArray)
    .onData { playlist ->
        // Build your playback queue by using list of Bursts
    }
    .onError { error ->
        // Handle error
    }

The getPlaylist function accepts ByteArray as an argument. A request included in the PCM file will be processed and a playlist of the bursts will be returned.

Step 4. Inform library about current playback state

Audioburst is obligated to provide content owners comprehensive information about content playback, therefore all play events need to be reported. This library implements that functionality, and the only event required is to inform when playback starts and stops, and return the current playback state every time the library requests that information.

If MediaBrowserServiceCompat is being used, we strongly recommend implementing the following functionalities there.

Playback start/stop

audioburstLibrary.start()
audioburstLibrary.stop()

If you are using Android's ExoPlayer then it can be easily done by implementing EventListener.onIsPlayingChanged:

override fun onIsPlayingChanged(isPlaying: Boolean) {
    super.onIsPlayingChanged(isPlaying)
    mediaSessionConnection.exoPlayerCallback?.onIsPlayingChanged(isPlaying)
    if (isPlaying) {
        audioburstLibrary.start()
    } else {
        audioburstLibrary.stop()
    }
}

Returning current playback state

This interface can be called by the library at any time, so please try to always return the current playback state, even when nothing is currently playing.

audioburstLibrary.setPlaybackStateListener(this)

override fun getPlaybackState(): PlaybackState? {
    return PlaybackState(
        positionMillis = contentPosition,
        url = currentUrl
    )
}

Full example using `MediaBrowserServiceCompat` and `ExoPlayer`

class MediaService : MediaBrowserServiceCompat(), Player.EventListener, PlaybackStateListener {

    private val exoPlayer: ExoPlayer = ...
    private val audioburstLibrary: AudioburstLibrary = ...
    private var currentPlaylist: List<String> = ...

    override fun onCreate() {
        super.onCreate()
        (...)
        exoPlayer.addListener(this)
        audioburstLibrary.setPlaybackStateListener(this)
    }

    override fun onIsPlayingChanged(isPlaying: Boolean) {
        super.onIsPlayingChanged(isPlaying)
        if (isPlaying) {
            audioburstLibrary.start()
        } else {
            audioburstLibrary.stop()
        }
    }

    override fun onDestroy() {
        audioburstLibrary.stop()
        audioburstLibrary.removePlaybackStateListener(this)
    }

    override fun getPlaybackState(): PlaybackState? {
        val currentIndex = exoPlayer.currentTimeline.getWindow(exoPlayer.currentWindowIndex, Timeline.Window())
        return PlaybackState(
            positionMillis = exoPlayer.contentPosition,
            url = currentPlaylist[currentIndex]
        )
    }
    
    (...)
}

Get Started - iOS

This guide is a quick walkthrough to add AudioburstMobileLibrary to an iOS app. We recommend XCode as the development environment for building an app with the AudioburstMobileLibrary.

Requirements

iOS 12.0+
Xcode 11

Add AudioburstMobileLibrary to your app

Step 1. Add AudioburstMobileLibrary dependency

You can use CocoaPods to install AudioburstPlayer by adding it to your Podfile:

platform :ios, '12.0'
use_frameworks!

target 'MyApp' do
    pod 'AudioburstMobileLibrary', '~> 0.0.7'
end

Step 2. Initialize `AudioburstLibrary` object

let audioburstLibrary = AudioburstLibrary(applicationKey: "YOUR_API_KEY_HERE")

You can use this class by instantiating its instance every time you need this or as a singleton.

Legacy support

Use the library's 'setAudioburstUserID' function to keep a pre-existing Audioburst API User ID.

audioburstLibrary.setAudioburstUserID(userId: "EXISTING_AUDIOBURST_API_USER_ID") { isSucces in
    // If isSuccess is true, then you are ready to use existing Audioburst API User ID
} onError: { error in
    // Handle error 
}

Step 3. Request Audioburst content

All the functions below lets you pass a closure that contains a requested data or error information.

Get all available playlists

audioburstLibrary.getPlaylists { playlists in
    // Display available playlists
} onError: { errorType in
    // Handle error
}

Get playlist information

audioburstLibrary.getPlaylist(playlistInfo: playlistInfo) { playlist in
    // Build your playback queue by using list of Bursts
} onError: { errorType in
    // Handle error
}

Get advertisement url

audioburstLibrary.getAdUrl(burst: burst) { adUrl in
    // Play ad
} onError: { errorType in
    // Handle error
}

Manage user preferences

The library also includes the capability to manage (get and update) user preferences.

audioburstLibrary.getUserPreferences { userPreferences in
    // Use user preferences
} onError: { error in
    // Handle error
}

audioburstLibrary.postUserPreferences(userPreferences: userPreferences) { userPreferences in
    // Use updated user preferences
} onError: { error in
    // Handle error
}

Get Personalized Playlist using async

audioburstLibrary.getPersonalPlaylist { pendingPlaylist in
    if (pendingPlaylist.isReady) {
        // Your playlist is ready
    } else {
        // Your playlist is still being prepared
    }
} onError: { error in
    // Handle error
}

Pass recorded PCM file

audioburstLibrary.getPlaylist(data: data) { playlist in
    // Build your playback queue by using list of Bursts
} onError: { errorType in
    // Handle error
}

The getPlaylist function accepts Data as an argument. A request included in the PCM file will be processed and a playlist of the bursts will be returned.

Step 4. Inform library about current playback state

Playback start/stop

audioburstLibrary.start()
audioburstLibrary.stop()

If you are using iOS's AVPlayer then it can be easily done in a following way:

private var statusObservation: NSKeyValueObservation?

let playerItem = AVPlayerItem(url: url)
statusObservation = player?.observe(\.timeControlStatus, options: [.new, .old], changeHandler: { [weak self]
    (playerItem, change) in
    switch (playerItem.timeControlStatus) {
    case .playing:
        self?.audioburstLibrary.start()
    default:
        self?.audioburstLibrary.stop()
    }
})
player = AVPlayer(playerItem: playerItem)

Returning current playback state

This interface can be called by the library at any time, so please try to always return the current playback state, even when nothing is currently playing.

audioburstLibrary.setPlaybackStateListener(playbackStateListener: self)

extension PlayerInteractor: PlaybackStateListener {
    func getPlaybackState() -> PlaybackState? {
        return PlaybackState(url: currentUrl, positionMillis: Int64(contentPositionMilis))
    }
}

Full example using `AVPlayer`

We recommend initializing and keeping PlayerInteractor in AppDelegate. This way you are sure you can return a current playback state every time library ask for it.

class PlayerInteractor {

    var player: AVPlayer?
    let audioburstLibrary = AudioburstLibrary(applicationKey: "123456")

    private var statusObservation: NSKeyValueObservation?

    init() {
        audioburstLibrary.setPlaybackStateListener(playbackStateListener: self)
        //get url and load item to play (...)
        let playerItem = AVPlayerItem(url: url)
        statusObservation = player?.observe(\.timeControlStatus, options: [.new, .old], changeHandler: { [weak self]
            (playerItem, change) in

            switch (playerItem.timeControlStatus) {
            case .playing:
                self?.audioburstLibrary.start()
            default:
                self?.audioburstLibrary.stop()
            }
        })

        player = AVPlayer(playerItem: playerItem)
    }
    
    deinit {
        audioburstLibrary.stop()
        audioburstLibrary.removePlaybackStateListener(playbackStateListener: self)
    }
}

extension PlayerInteractor: PlaybackStateListener {
    func getPlaybackState() -> PlaybackState? {
        guard let asset = (player?.currentItem?.asset) as? AVURLAsset, let player = self.player else {
            return nil
        }
        let url = asset.url.absoluteString
        let contentPositionMilis = (player.currentTime().seconds)/1000
        return PlaybackState(url: url, positionMillis: Int64(contentPositionMilis))
    }
}

AudioburstMobileLibrary 0.0.30

AudioburstMobileLibrary 0.0.30

AudioburstMobileLibrary 0.0.30

Audioburst Mobile Library

Introduction

Features

Prerequisites

Audioburst API key

Get Started - Android

Add AudioburstMobileLibrary to your app

Step 1. Add AudioburstMobileLibrary dependency

Step 2. Initialize AudioburstLibrary object

Legacy support

Step 3. Request Audioburst content

Get all available playlists

Get playlist information

Get advertisement url

Manage user preferences

Get Personalized Playlist using async

Pass recorded PCM file

Step 4. Inform library about current playback state

Playback start/stop

Returning current playback state

Full example using MediaBrowserServiceCompat and ExoPlayer

Get Started - iOS

Requirements

Add AudioburstMobileLibrary to your app

Step 1. Add AudioburstMobileLibrary dependency

Step 2. Initialize AudioburstLibrary object

Legacy support

Step 3. Request Audioburst content

Get all available playlists

Get playlist information

Get advertisement url

Manage user preferences

Get Personalized Playlist using async

Pass recorded PCM file

Step 4. Inform library about current playback state

Playback start/stop

Returning current playback state

Full example using AVPlayer

Privacy Policy

Terms of Service

Step 2. Initialize `AudioburstLibrary` object

Full example using `MediaBrowserServiceCompat` and `ExoPlayer`

Step 2. Initialize `AudioburstLibrary` object

Full example using `AVPlayer`