Apple Music 接入指南

你只需要准备 Apple Music 的应用权限、自己的用户登录体系，以及我们提供的服务地址。Apple Music 登录和音频播放由 Apple 官方 SDK 在用户设备上完成。

本服务不会下载、保存、转码或转发 Apple Music 音频，也不会接收 Apple ID、Apple Music 用户令牌或音频地址。

可以使用的功能

搜索歌曲、专辑和歌单，查看详情
替换、追加、上一首、下一首播放队列
iOS 控制中心、Android 通知栏和锁屏控制
收藏、播放记录、推荐和应用内歌单
删除本服务中的用户产品数据
接入状态和错误上报

客户需要准备

iOS App ID 已启用 MusicKit，并使用客户团队签名。
Android 使用 Apple Developer 下载的官方 MusicKit Authentication 和 Media Playback AAR。
客户应用自己的登录系统。传给本服务的是客户应用会话凭证，不是 Apple Music 用户令牌。
至少一台登录了有效 Apple Music 订阅的实体 iOS 或 Android 设备。

接入顺序

完成客户应用登录。
配置服务地址和应用会话凭证。
调用官方 MusicKit 授权流程。
用 MusicKit 获取歌曲信息，并在本机解析后创建播放队列。
需要跨设备保存时，调用收藏、歌单和播放记录接口。
按接口约定上报状态和错误。

用户设备 -> Apple Music 官方服务
本服务只负责应用数据和短期接口凭证

iOS 配置

APPLE_MUSIC_PRODUCT_SERVICE_URL=<我们提供的服务地址>
APPLE_MUSIC_APP_SESSION_BEARER=<客户应用当前登录会话>

将 AppleMusicStreamingKit.xcframework 加入工程，启动时请求 MusicKit 授权，然后使用原生播放器播放。

Android 配置

appleMusicTokenEndpoint=<服务地址>/v1/apple-music/developer-token
appleMusicClientBearer=<客户应用当前登录会话>
appleMusicProductServiceUrl=<服务地址>
appleMusicProductServiceBearer=<客户应用当前登录会话>

将我们的 apple-music-streaming-release.aar 和 Apple 官方 AAR 加入工程。正式应用不要把测试凭证写死在 APK 中。

常用接口

请求头：Authorization: Bearer <客户应用会话凭证>。完整格式以服务地址下的 /openapi.json 为准。

功能	接口
Android 播放凭证	`GET /v1/apple-music/developer-token`
收藏	`GET/PUT/DELETE /v1/me/favorites...`
播放结果	`POST /v1/me/playback-events`
推荐	`GET /v1/me/recommendations`
应用歌单	`GET/POST /v1/me/app-playlists...`
删除本服务数据	`DELETE /v1/me/product-data`
运行状态	`POST /v1/me/telemetry/events`
安全日志	`POST /v1/me/telemetry/logs`

失败重试

一次用户操作生成一个 UUID Idempotency-Key。
超时或响应丢失时，用完全相同的请求和 key 重试。
不要用同一个 key 提交另一首歌曲或另一个歌单名称。

上线前检查

□ 两个平台都能完成授权和原生播放
□ 客户登录会话可以获取和刷新
□ 服务地址和凭证通过运行时配置注入
□ 在目标地区验证订阅和目录版权
□ 播放、后台控制、收藏、歌单和重试流程已验收
□ 不向支持人员提交 Apple 密码、账户凭证或完整请求头

测试地址

https://apple-music-api-prelaunch.luxhub.top

正式环境地址由项目上线时单独提供。测试地址只用于开发和验收。

获取帮助

提交平台、应用版本、系统版本、发生时间、接口路径、HTTP 状态码、请求 ID 和不包含隐私的错误描述。不要提交 Apple 账户、密码、播放凭证或音频地址。