警告：这是 Spotify iOS SDK 的测试版本。

Spotify iOS SDK 说明书

欢迎来到 Spotify iOS SDK！这份说明书是为那些想开发包含 Spotify 相关功能的 iOS 应用的人准备的，比如音频流、播放列表操作、搜索等。

使用此 SDK 受 开发者使用条款 的约束。

测试版本信息

我们提前发布这个 SDK 是为了从开发者社区中获得对我们 iOS SDK 将来的反馈。请在我们 问题跟踪器 上提交关于缺失问题或错误的反馈，确保您先搜索现有问题并为它们发声，而不是重复提交。

有关已知问题和发行说明，请参阅 CHANGELOG.md 文件。

要求

Spotify iOS SDK 需要 iOS 7 或更高版本的部署目标。以下架构受到支持：设备上为 armv7、armv7s 和 arm64，iOS 模拟器上为 i386 和 x86_64。请勿将 i386 和 x86_64 切片用于构建 Mac 应用程序。

入门

将 Spotify iOS SDK 添加到应用程序很容易

1. 将 Spotify.framework 库添加到您的 Xcode 项目。
2. 将 -ObjC 标志添加到您项目中的 "其他链接器标志" 构建设置。
3. 将 AVFoundation.framework 添加到您项目构建阶段的 "链接二进制与库" 中。
4. 在源文件中引入 #import <Spotify/Spotify.h> 并继续！

该库的头文件有详细的文档，并附带了一个 Xcode 文档集，可以由 Xcode 本身以及像 Dash 这样的应用程序进行索引。这，加上包含的示例项目，应该为您提供了一切需要的东西。可以帮助您开始的类包括

• SPTAuth 包含用户身份验证的方法。请参阅 "基本身份验证" 示例项目以获取该功能的实际示例。请务必阅读下面的 "身份验证和权限" 以及 "会话寿命" 部分，因为身份验证相当复杂。

  注意：要执行音频播放，您必须在使用 SPTAuth 时请求 SPTAuthStreamingScope 权限。为此，传递一个包含常量的数组到 -loginURLForClientId:withRedirectURL:scopes:responseType:。如果需要，提供的演示项目已经这样做。

• 元数据类包含执行相应元数据查找的方法。 SPTUser 用于用户信息，SPTSearch 用于搜索。 请查看元数据类列表

认证和作用域

您可以在 Spotify 开发者网站的“我的应用”部分生成您应用的客户端 ID、客户端密钥并定义您的回调 URI。之前 SDK 版本提供的临时密钥将无法与 Beta 3 及更高版本一起使用。

当将用户连接到您的应用时，您 必须 提供应用操作需要的作用域。作用域是访问用户账户中某个部分的权限，如果您不请求所需的作用域，则在尝试执行各种任务时将收到权限拒绝错误。

访问非特定于用户的信息时，您不需要作用域，例如执行搜索、查找元数据等。

常见作用域包括

• SPTAuthStreamingScope 允许 Premium 用户的音乐流媒体播放。

• SPTAuthUserReadPrivateScope 允许访问用户的私人信息，例如完整显示名称、用户照片等。

• SPTAuthPlaylistReadScope 和 SPTAuthPlaylistReadPrivateScope 分别允许访问用户的公共和私有播放列表。

• SPTAuthPlaylistModifyScope 和 SPTAuthPlaylistModifyPrivateScope 分别允许修改用户的公共和私有播放列表。

作用域的完整列表可在文档和 SPTAuth.h 中找到。

如果用户已连接到您的应用后，您应用的权限需求发生变化，您需要清除存储的凭据并使用新的权限重新对用户进行认证。

重要： 仅请求您应用需要的权限。例如，当您的应用不使用播放列表时请求播放列表访问，是不良的做法。

会话有效期

一旦用户完成认证，您将收到一个 SPTSession 对象，这将允许您执行认证请求。此会话在特定时间内有效，必须刷新。

您可以通过在 SPTSession 上调用 -isValid 方法来检查会话是否仍然有效，并通过 expirationDate 属性来查看截止日期。一旦会话失效，您可以使用 SPTAuth 的 -renewSession:withServiceEndpointAtURL:callback: 方法来更新它。

例如，当您的应用启动时，您将想要恢复存储的会话，然后检查它是否有效，并在需要时更新它。您的代码流程可能如下

SPTSession *session = …; // Restore session

if (session == nil) {
    // No session at all - use SPTAuth to ask the user
    // for access to their account.
    [self presentFirstTimeLoginToUser];

} else if ([session isValid]) {
    // Our session is valid - go straight to music playback.
    [self playMusicWithSession:session];

} else {
    // Session expired - we need to refresh it before continuing.
    // This process doesn't involve user interaction unless it fails.
    NSURL *refreshServiceEndpoint = …;
    [SPTAuth defaultInstance] renewSession:session 
                                   callback:^(NSError *error, SPTSession *session)
     {
          if (error == nil) {
                [self playMusicWithSession:session];
            } else {
                [self handleError:error];
            }
    }];
}

初学者教程

请访问 开发者网站 了解使用 Spotify iOS SDK 创建简单应用分步创建的步骤

从 CocoaLibSpotify 迁移

CocoaLibSpotify 基于包含大量遗留代码且非常复杂的 libspotify 库。虽然这提供了大量的功能，但它也可能占用大量的 RAM 和 CPU 资源，这在移动平台中并不理想。

Spotify iOS SDK 基于全新的技术堆栈，旨在避免这些问题，同时仍然提供丰富的功能集。由于这个新的架构，我们决定从头开始编写 Spotify iOS SDK 的 API，而不是试图将新技术挤入 CocoaLibSpotify 的 API。这导致了一个更易于使用、与 CocoaLibSpotify 相比 CPU 和 RAM 占用量大大减少的库。

Spotify iOS API 与 CocoaLibSpotify 并不完全一致。它包含了 CocoaLibSpotify 所不具备的功能，而 CocoaLibSpotify 也有的功能 Spotify iOS SDK 没有实现。我们正在努力缩小这种差距，如果 Spotify iOS SDK 缺少您特别重要的功能，请与我们联系，以便我们正确地优先处理。

由于 CocoaLibSpotify 和 Spotify iOS SDK 之间的 API 和功能差异，我们理解迁移可能很困难。因此，在 SDK 离开测试状态后，CocoaLibSpotify 还将持续可用一段时间。