AudioburstMobileLibrary 0.0.30

AudioburstMobileLibrary 0.0.30

×

由 Kamil Halko、Gal Klein、Yosi Wigman 维护。

AudioburstMobileLibrary 0.0.30

  • 由
  • Audioburst

Audioburst Mobile Library

简介

AudioburstMobileLibrary 是一个跨平台库，它允许方便地访问 Audioburst 的内容 API。可以访问播放列表，用户可以选择播放列表，还可以请求有关播放列表的附加信息。

有关库使用的流程和对象的信息，请参阅我们的wiki 页面

特性

AudioburstMobileLibrary 提供了一个简单的 API，让您

  • 获取所有可用的播放列表
  • 获取特定播放列表的信息，包括 Burst 列表
  • 轻松地处理向 API 发送所需事件的请求。

先决条件

AudioBurst API密钥

库需要通过 AudioBurst发布者 获得的应用程序密钥。

入门 - Android

本指南是添加AudioBurstMobileLibrary到Android应用程序的快速浏览。我们建议使用Android Studio作为开发环境来构建具有AudioBurstMobileLibrary的应用程序。

将AudioBurstMobileLibrary添加到您的应用程序

第一步：添加AudioBurstMobileLibrary依赖

Download Android

将AudioBurstMobileLibrary Android SDK添加到您的项目中。为此，请在您的应用程序级别的build.gradle文件中添加以下依赖项：

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

库是用Kotlin语言编写的，并使用Coroutines，因此为了支持它，您需要在应用程序级别的build.config文件中添加以下配置：

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

如果您在Kotlin Coroutines依赖项上遇到“重复类”，则需要在以下方式中从AudioBurstPlayer库中排除它们：

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

第二步：初始化AudioburstLibrary对象

val audioburstLibrary: AudioburstLibrary = AudioburstLibrary("YOUR_API_KEY_HERE")

您可以通过每次需要时实例化其实例或作为单例来使用此类。

旧版支持

使用库中的 'setAudioburstUserID' 函数保留现有的 Audioburst API 用户 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 
    }

步骤 3. 请求 Audioburst 内容

以下所有函数都是 挂起的，这意味着您需要使用 CoroutineScope 调用它们。此外，它们返回的 Result 对象可以是 Data 或 Error。库提供了一些方便的扩展函数，使得处理此类对象变得更容易。查看 Result 类，了解更多信息。

获取所有可用播放列表

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

获取播放列表信息

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

获取广告 URL

您也可以在播放列表项（爆发）之前播放广告。要这样做，通过调用 Burst.isAdAvailable 检查特定的 Burst 是否有广告。如果可用的广告，则在播放 Burst 内容之前调用 getAdUrl，这允许带有广告的 Burst 播放。

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

管理用户偏好设置

该库还包括管理（获取和更新）用户偏好的功能。

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

使用异步方法获取个性化播放列表

该库包括根据用户的偏好构建个性化播放列表的能力。为了缩短个性化播放列表的加载时间，该库公开了“订阅”播放列表中持续变化的能力。订阅功能允许在添加新Burst到播放列表时接收通知，并检查播放列表是否已准备好。

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
            } 
    }

传递已录制的PCM文件

AudioburstLibrary能够处理包含要播放的录制请求的原始音频文件。您可以将一个语音命令录制下来，说明您想听什么，然后将其上传到您的设备，并使用AudioburstLibrary来获取与该主题相关的Bursts。

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

getPlaylist函数接受ByteArray作为参数。PCM文件中包含的请求将进行处理，并返回一段包含Bursts的播放列表。

步骤4. 通知库当前的播放状态

Audioburst有义务提供关于内容播放的全面信息，因此所有播放事件都需要报告。该库实现了这项功能，所需唯一的事件是在播放开始和停止时通知库，以及每次库请求该信息时返回当前的播放状态。

如果正在使用MediaBrowserServiceCompat，我们强烈建议在该处实现以下功能。

播放开始/停止

audioburstLibrary.start()
audioburstLibrary.stop()

如果您使用的是Android的ExoPlayer，则可以通过实现EventListener.onIsPlayingChanged轻松完成。

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

返回当前播放状态

此接口可以在任何时间由库调用，因此请务必始终返回当前播放状态，即使当前没有正在播放的内容。

audioburstLibrary.setPlaybackStateListener(this)

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

使用MediaBrowserServiceCompat和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]
        )
    }
    
    (...)
}

入门 - iOS

本指南是一个快速说明，介绍如何将AudioburstMobileLibrary添加到iOS应用程序中。我们建议将XCode作为使用AudioburstMobileLibrary构建应用程序的开发环境。

要求

  • iOS 12.0+
  • Xcode 11

将AudioburstMobileLibrary添加到您的应用程序

步骤 1. 添加 AudioburstMobileLibrary 依赖

您可以使用 CocoaPods 通过将其添加到您的 Podfile 来安装 AudioburstPlayer

platform :ios, '12.0'
use_frameworks!

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

步骤 2. 初始化 AudioburstLibrary 对象

let audioburstLibrary = AudioburstLibrary(applicationKey: "YOUR_API_KEY_HERE")

您可以通过每次需要时实例化其实例或作为单例来使用此类。

遗留支持

使用库中的 'setAudioburstUserID' 函数保留现有的 Audioburst API 用户 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 
}

步骤 3. 请求 Audioburst 内容

以下所有函数都允许您传递包含请求数据或错误信息的闭包。

获取所有可用播放列表

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

获取播放列表信息

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

获取广告URL

您也可以在播放列表项（爆发）之前播放广告。要这样做，通过调用 Burst.isAdAvailable 检查特定的 Burst 是否有广告。如果可用的广告，则在播放 Burst 内容之前调用 getAdUrl，这允许带有广告的 Burst 播放。

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

管理用户偏好

该库还包括管理（获取和更新）用户偏好的功能。

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
}

使用异步方式获取个性化播放列表

该库包括根据用户的偏好构建个性化播放列表的能力。为了缩短个性化播放列表的加载时间，该库公开了“订阅”播放列表中持续变化的能力。订阅功能允许在添加新Burst到播放列表时接收通知，并检查播放列表是否已准备好。

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

传递录制好的PCM文件

AudioburstLibrary能够处理包含要播放的录制请求的原始音频文件。您可以将一个语音命令录制下来，说明您想听什么，然后将其上传到您的设备，并使用AudioburstLibrary来获取与该主题相关的Bursts。

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

getPlaylist函数接受Data作为参数。PCM文件中的请求会被处理，并返回 bursts 的播放列表。

第4步：告知库当前播放状态

Audioburst有义务提供关于内容播放的全面信息，因此所有播放事件都需要报告。该库实现了这项功能，所需唯一的事件是在播放开始和停止时通知库，以及每次库请求该信息时返回当前的播放状态。

播放开始/停止

audioburstLibrary.start()
audioburstLibrary.stop()

如果您使用iOS的AVPlayer，则可以通过以下方式进行

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)

返回当前播放状态

此接口可以在任何时间由库调用，因此请务必始终返回当前播放状态，即使当前没有正在播放的内容。

audioburstLibrary.setPlaybackStateListener(playbackStateListener: self)

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

使用 AVPlayer 的完整示例

我们推荐在 AppDelegate 中初始化并保持 PlayerInteractor，这样每次库请求时，你都可以确保返回当前播放状态。

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))
    }
}

隐私政策

隐私政策

服务条款

服务条款