LwayveSDK 3.3.0

LwayveSDK 3.3.0

×

许可证 未知
发布最新发布2018年8月

由Lwayve维护。

LwayveSDK 3.3.0

  • 由
  • Lixar, Inc

LWAYVE iOS SDK

以下文档提供了关于 LWAYVE 平台背景信息，并为 LWAYVE iOS SDK 的设置和使用提供了说明。文档内容分为以下几部分

第一章：介绍 LWAYVE 和情境音频体验

背景

LWAYVE 是一个音频平台，为活动参与者提供情境式音频体验，并可嵌入到任何移动应用程序中，以增强其功能。情境式音频体验充当个性化音频向导，使任何活动尽可能有趣、简便和愉悦。

情境式音频体验基于听众的当前情境提供最佳音频。

  • 时间
  • 地点
  • 用户喜好
  • 关于和围绕活动的最新信息

情境式音频体验是：

  • 情境化的。在情境式音频体验中的音频将为每个参加活动的用户而不同，这取决于他们的时间、地点、用户喜好和情况。
  • 精心编排的。情境式音频体验经过精心编排和策划，以确保活动获得最高质量的音频体验。
  • 集成的。LWAYVE 平台可以被集成到最流行的移动设备上的任何移动应用程序中，并对听众的交互要求最低。
  • 可衡量的。使用 LWAYVE 收集的使用数据允许客户衡量音频广告对听众行动的影响，然后相应优化情境式音频体验。

主要参与者是谁？

LWAYVE 平台有六个主要参与者。

  • 开发者：开发者将 LWAYVE 平台集成到移动应用程序中。通过整合 LWAYVE，移动应用程序将包含一个播放按钮，听众可以点击以根据时间、地点和用户喜好获取情境式音频体验。
  • 体验设计师：体验设计师编排情境式音频体验并获取内容。体验设计师本质上是在根据事件（例如，音乐节）构建情境式音频体验。情境式音频体验包含将在听众的时间、地点和用户喜好基础上传递给听众的音频。例如，音乐节体验设计师可以选择让听众在前往活动的路上听到交通信息，在活动中听到舞台日程。
  • 听众：享受基于时间、地点和用户喜好的高价值、个性化情境式音频体验的最终用户。听众通过在移动应用程序上点击播放按钮来收听情境式音频体验。
  • 体验指挥：体验指挥是现场的眼睛和耳朵。体验指挥控制情境式音频体验中的情境性音频，并根据实时信息进行调整。例如，在音乐节上，如果原定于晚上 9 点举行的音乐会已改为晚上 10 点，体验指挥可以相应调整情境式音频体验。
  • 客户：购买LWAYVE以实施情境音频体验的公司或个人。LWAYVE集成到客户的移动应用程序中，以向听众提供情境音频体验。
  • 管理员：LWAYVE平台由Lixar全面管理；然而，客户自行管理他们的情境音频体验和用户角色。

LWAYVE平台有哪些组成部分？

LWAYVE的组件可以分为以下主要类别：移动SDK、客户移动应用程序、LWAYVE服务和可选的ProxSee服务。

移动SDK

作为其角色的一部分，开发者将以下两个SDK集成到移动应用程序中

  • LWAYVE SDK：LWAYVE SDK处理位置（借助ProxSee SDK）、时间和情境音频参数。
  • ProxSee SDK：ProxSee SDK将位置标签传递给LWAYVE SDK。有关ProxSee SDK的完整信息，请参阅https://github.com/proxsee。

客户移动应用程序

  • 客户移动应用程序：这是集成了LWAYVE和ProxSee SDK的移动应用程序。通过集成SDK，移动应用程序中会出现一个简单的LWAYVE播放按钮。所有听众需要做的就是点击播放按钮开始他们的情境音频体验。

体验服务和情境音频体验

  • 体验服务：这是体验设计师创建情境音频体验的后端平台。
  • 情境音频体验：这是在体验服务上创建的内容。
    • 精选音频：这是在初步规划和发展阶段由体验设计师收集的音频。这些音频是根据听众的时间、地点和用户喜好计划的。例如，对于一个音乐节，体验设计师可能会根据演出时间表创建基于精选音频的内容。
    • 情境音频：这是由活动现场的经验导体“在地面上”收集的音频。例如，在音乐节上，突发的天气变化可能会促使经验导体为了恶劣天气的安全措施创建情境音频（例如，建议听众寻找避难所）。
    • 时间：情境音频体验将根据时间提供给听众不同的内容。例如，在音乐节上，下午4点大门开放时，音频可能与入口排队有关，而在晚上8点，音频可能与音乐会日程有关。
    • 位置：情境音频体验将根据听众的位置而有所不同。例如，如果听众站在食物帐篷旁边，音频可能与菜单项目及饮食特价有关。
    • 用户喜好：这是在客户移动应用程序中由听众设置的设置。

如何使用LWAYVE？

以下图像描绘了LWAYVE情境音频体验的总体工作流程。

Communication Diagram

第二节：在iOS项目中实现LWAYVE和ProxSee SDKs

在iOS项目中整合LWAYVE和ProxSee SDKs是一个简单的过程

  1. 将 LWAYVE SDK（可选 ProxSee SDK）作为依赖项添加
  2. 配置应用后台模式
  3. 设置推送通知
  4. 初始化 LWAYVE（可选 ProxSee SDK）
  5. 设置品牌播放控制

先决条件

以下指令提供了以下假设

  • 已配置特定的客户环境
  • 已提供授权令牌
  • 已提供ProxSee API密钥
  • 经验设计师已创建情境音频体验并将其上传到您的环境中。或者已上传示例Lixar体验到您的环境中。
  • 情境音频体验对应的音频文件已上传到您的环境
  • 如果使用ProxSee服务，则在ProxSee环境中已定义LWAYVE情境音频体验所需的位置标记

要添加和管理 LWAYVE 和 ProxSee SDK 作为您的 iOS 项目中的依赖项，您必须首先安装 CocoaPods。

$ gem install cocoapods

在您的 iOS 项目中，创建一个名为 Podfile 的文件。

在 Podfile 中添加 LWAYVE 依赖项。

pod 'LwayveSDK'

(可选) 添加 ProxSee 依赖项。

pod 'LwayveSDK/ProxSee'

运行安装命令。

$ pod install

添加 Plist 值

以下 Plist 值是 Lwayve SDK 所必需的。

  • NSMicrophoneUsageDescription：用于用户生成音频必需。

（可选）有关 ProxSee 所需的 Plist 值，请参阅 https://github.com/proxsee/sdk-ios#add-the-proxsee-sdk-to-your-ios-project

设置推送通知

推送通知用于通知 SDK 体验更新和环境音频。

SDK 将处理推送通知。以下是一个推送通知负载的示例。

{
  "event": "experience.updated",
  "aps": {
    "content-available": 1
  },
  "experience_id": 194950
}

启用推送通知

要为您的应用程序启用推送通知，请参阅 Apple 文档中的启用推送通知。

生成身份验证令牌

为了允许推送通知，必须向 Lixar 提供一个 APNs 密钥 (.p8)。请参阅 Apple 文档中的使用身份验证令牌与 APNs 通信。

注意：建议只为该密钥启用 APNs。

初始化 LWAYVE（以及可选的 ProxSee SDK）

下一步是初始化（启动）LWAYVE SDK。

初始化 LWAYVE SDK

初始化 LWAYVE SDK 时，您需要传递 Lixar 提供给您的高级认证令牌。

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

  // Create the configuration used for the LWAYVE SDK.
  let configuration = LwayveSDKConfiguration(baseURL: URL(string: settings.value(forSetting: .BaseURL)),
  authenticationToken: settings.value(forSetting: .AuthenticationKey))

  // Set the delegate before calling LwayveSDK.sharedSDK.initialize to be able to receive lwayveSDK(didInit:) callback
  LwayveSDK.sharedSDK.add(delegate: self)

  // Attempt to initialize the LWAYVE SDK using the configuration values.
  // This may fail if the SDK is already initialized, the persistent storage cannot be created, or if an empty authenticationToken is provided.
  do {
    try LwayveSDK.sharedSDK.initialize(configuration: configuration)
  } catch {
    NSLog("LwayveSDK initialization error: \(error)")
  }

  // Pass the launch options to the LWAYVE SDK.
  // The launch options are used by the SDK to retrieve any relevant notification information.
  LwayveSDK.sharedSDK.handleApplication(application, didFinishLaunchingWithOptions: launchOptions)

  return true
}

// ...

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
  // Pass the notification data to the LWAYVE SDK so that it can process any information relevant to it.
  LwayveSDK.sharedSDK.handleApplication(application, didReceiveRemoteNotification: userInfo, fetchCompletionHandler: completionHandler)
}

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  // Pass the device token to the Lwayve SDK
  LwayveSDK.sharedSDK.handleApplication(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
}

(可选) 使用 ProxSee 初始化 Lwayve，导入带有 ProxSee 的 Lwayve 并替换初始化方法。

import LwayveSDK

...

do {
  try LwayveSDK.sharedSDK.initializeWithProxSee(configuration: configuration)
} catch {
  NSLog("LwayveSDK initialization error: \(error)")
}

设置定制播放控制

LwayvePlaybackControlView 可用于为 LWAYVE SDK 提供所需的全部 UI。它提供播放、跳过和回退操作，以及播放状态的指示。

LwayvePlaybackControlView 是 UIView 的子类。它可以与或没有 Storyboard 或 Xib 一起使用。

使用 Storyboard 或 Xib

使用 Storyboard 或 Xib 添加 LwayvePlaybackControlView

  1. 添加一个视图
  2. 将视图类设置为 LwayvePlaybackControlView。
  3. 将模块设置为 LwaveSDK。
  4. 为视图创建一个 IBOutlet。
  5. 将 SDK 实例分配给 LwayvePlaybackControlView.lwayveSDK 属性（例如，self.playbackControl.lwayveSDK = LwayveSDK.sharedSDK）。

从代码中

从代码中添加 LwayvePlaybackControlView

  1. 创建一个 LwayvePlaybackControlView 实例（例如，let playbackControl = LwayvePlaybackControlView(frame: frame))。
  2. 将 SDK 实例分配给 LwayvePlaybackControlView.lwayveSDK 属性（例如，playbackControl.lwayveSDK = LwayveSDK.sharedSDK）。
  3. 将视图添加到您的父视图中。

为其他语言提供可本地化的字符串（可选）

定制播放控制显示一些带有文本的 UI 控件和警报，这可能需要本地化。当前版本已经包含法语和西班牙语的翻译。备用语言是英语。

如果您希望 Lwayve SDK 品牌播放控制支持更多语言，您可以提供自己的翻译。为此，您需要将密钥添加到您的应用 Localizable.strings 或 Localizable.stringsdic 文件中。所有密钥的完整列表可在以下文件中找到：Localizable.strings。

另请参阅 PlaybackControlSampleApplication

第3节：测试 LWAYVE

API

您可以使用 Swagger 上的记录来测试 LWAYVE。您可以通过以下 URL 访问 Swagger

https://gateway.lwayve.com/swagger-ui/index.html

LWAYVE SDK 参考

有关 LWAYVE SDK 参考信息（例如，类、全局变量、枚举、协议和结构体）请参阅https://lwayve.github.io/ios/docs/api_docs/Classes.html。

第4节：剪辑上下文操作

每个音频剪辑可能都伴随着与剪辑相关的辅助操作，例如打开网页、打开地图、分享等。LWAYVE 提供了 5 个默认图标和文本

  1. 门票 - 这可以是一个包含艺术家的门票信息（如正在播放的艺术家或音乐节）的网站 URL。
  2. 地图 - 这可以用于艺术家演唱会地点、景点或赞助商位置的谷歌地图位置。
  3. 链接 - 正在播放的音频的相关链接
  4. 分享 - 可以用于听众在社交媒体上分享的字符串
  5. 酒店 - 包含艺术家演奏活动地点附近酒店的 URL

带有品牌播放控制的剪辑上下文操作

操作通过LWAYVE品牌播放控制进行渲染（也请参阅设置品牌播放控制）。用户在播放按钮上进行长按或向下滑动操作时，可以从外环访问这些操作。

外观定制

LWAYVE品牌播放控制的Outer Band中使用的默认图标和文本资源，可根据需要替换。覆盖的值将适用于体验中的所有音频片段。也请参阅：API 和 代码示例

音频录制操作

音频录制操作是第6个可选操作。它允许用户录制自己的简短录音，并将其提交到体验播放列表中进行考虑。

无品牌播放控制的片段上下文操作

如果您想在没有使用品牌播放控制的情况下使用LWAYVE服务，您仍然可以通过以下API访问片段上下文操作：

访问当前播放的音频片段

https://lwayve.github.io/ios/docs/api_docs/Protocols/PlaylistControlProtocol.html#/c:@M@LwayveSDK@objc(pl)LwayvePlaylistControlProtocol(py)audioQueue

检索操作界面信息

https://lwayve.github.io/ios/docs/api_docs/Protocols/ClipActionsProtocol.html#/c:@M@LwayveSDK@objc(pl)LwayveClipActionsProtocol(im)loadActionsWithActions:completion

执行剪辑操作

https://lwayve.github.io/ios/docs/api_docs/Protocols/ClipActionsProtocol.html#/c:@M@LwayveSDK@objc(pl)LwayveClipActionsProtocol(im)performClipAction:completion

音频录制上传操作

https://lwayve.github.io/ios/docs/api_docs/Protocols/UserRecordedAudioUploadProtocol.html#/c:@M@LwayveSDK@objc(pl)UserRecordedAudioUploadProtocol(py)maximumUserRecordedAudioDuration

参见代码示例

第5节：Apple Music

Lwayve SDK 现在可以满足最低配置要求播放 Apple Music。

要求

所需做的只是将一个新的 key NSAppleMusicUsageDescription 添加到您的 app 的 info.plist 文件中，并添加对用户的描述，说明为什么需要此权限。

<key>NSAppleMusicUsageDescription</key>
<string>We need permission to access your apple music in order for us to play apple music songs.</string>