ios sdk
v3.0.0
เฟรมเวิร์ก Spotify iOS ช่วยให้แอปพลิเคชันของคุณโต้ตอบกับแอพ Spotify ที่ทำงานอยู่เบื้องหลังบนอุปกรณ์ของผู้ใช้ได้ ความสามารถต่างๆ ได้แก่ การอนุญาต การรับข้อมูลเมตาสำหรับแทร็กและบริบทที่กำลังเล่นอยู่ ตลอดจนการออกคำสั่งการเล่น
โปรดทราบ: การใช้เครื่องมือสำหรับนักพัฒนา Spotify แสดงว่าคุณยอมรับข้อกำหนดการใช้งานสำหรับนักพัฒนาของเรา
Spotify iOS SDK คือชุดของออบเจ็กต์น้ำหนักเบาที่เชื่อมต่อกับแอพ Spotify และให้คุณควบคุมมันในขณะที่การเล่นที่หนักหน่วงทั้งหมดถูกถ่ายไปยังแอพ Spotify เอง แอพ Spotify ดูแลการเล่น การเชื่อมต่อเครือข่าย การแคชออฟไลน์ และการรวมเพลงเข้ากับระบบปฏิบัติการ ทำให้คุณมุ่งเน้นไปที่ประสบการณ์ผู้ใช้ของคุณ การย้ายจากแอปของคุณไปยังแอป Spotify และในทางกลับกันเป็นประสบการณ์ที่ได้รับการปรับปรุง โดยที่การเล่นและข้อมูลเมตาจะซิงค์กันอยู่เสมอ
คุณสมบัติที่สำคัญ
การยื่นข้อบกพร่อง
ส่วนประกอบ
การโทรระยะไกลของแอปทำงานอย่างไร
เงื่อนไขการใช้งาน
บทช่วยสอน
คำถามที่พบบ่อย
เราชอบคำติชมจากชุมชนนักพัฒนา ดังนั้นโปรดส่งฟีเจอร์หรือข้อบกพร่องที่ขาดหายไปได้ที่เครื่องมือติดตามปัญหาของเรา ตรวจสอบให้แน่ใจว่าคุณค้นหาปัญหาที่มีอยู่ก่อนที่จะสร้างปัญหาใหม่
เปิดตั๋วข้อผิดพลาด | เปิดคำขอคุณลักษณะ
เฟรมเวิร์ก Spotify iOS ต้องมีเป้าหมายการใช้งานเป็น iOS 12 หรือสูงกว่า สถาปัตยกรรมต่อไปนี้ได้รับการสนับสนุนใน SDK:
SPTAppRemoteAlbumSPTAppRemoteArtistSPTAppRemoteLibraryStateSPTAppRemotePlaybackRestrictionsSPTAppRemotePlaybackOptionsSPTAppRemotePlayerStateSPTAppRemoteTrackSPTAppRemoteContentItemSPTAppRemoteUserCapabilitiesSPTAppRemoteImageRepresentableSPTConfigurationจุดเริ่มต้นหลักในการเชื่อมต่อกับแอพ Spotify และดึงส่วนประกอบ API ใช้สิ่งนี้เพื่อสร้าง ตรวจสอบ และยุติการเชื่อมต่อ
ส่งคำสั่งที่เกี่ยวข้องกับการเล่นเช่น:
ดึงข้อมูลรูปภาพสำหรับ SPTAppRemoteImageRepresentable
ดึงข้อมูล/สมัครสมาชิก/ตั้งค่าข้อมูลที่เกี่ยวข้องกับผู้ใช้ เช่น:
SPTAppRemoteUserCapabilitiesดึงเนื้อหาที่แนะนำสำหรับผู้ใช้
เมื่อคุณโต้ตอบกับ App Remote API ใดๆ คุณจะส่งผ่านบล็อก SPTAppRemoteCallback ที่ถูกเรียกใช้พร้อมกับรายการผลลัพธ์ที่คาดหวังหรือ NSError หากการดำเนินการล้มเหลว การบล็อกจะถูกทริกเกอร์หลังจากได้รับคำสั่งจากแอป Spotify (หรือหากไม่สามารถเชื่อมต่อได้)
นี่คือตัวอย่างการใช้ SPTRemotePlayerAPI เพื่อข้ามเพลง:
[appRemote.playerAPI skipToNext: ^( id _Nullable result, NSError * _Nullable error) {
if (error) {
// Operation failed
} else {
// Operation succeeded
}
}];เรามีโปรเจ็กต์ตัวอย่างบางส่วนเพื่อช่วยให้คุณเริ่มต้นใช้งาน iOS Framework ในโฟลเดอร์ DemoProjects ดู Readme ในโฟลเดอร์ DemoProjects สำหรับข้อมูลเพิ่มเติมเกี่ยวกับสิ่งที่แต่ละตัวอย่างทำ
ในการสื่อสารกับแอป Spotify แอปพลิเคชันของคุณจะต้องได้รับอนุญาตจากผู้ใช้เพื่อควบคุมการเล่นก่อน โดยใช้การอนุญาตในตัวสำหรับ App Remote ในการทำเช่นนั้น คุณจะต้องขอมุมมองการอนุญาตเมื่อเชื่อมต่อกับ Spotify เฟรมเวิร์กจะขอขอบเขต app-remote-control โดยอัตโนมัติ และแสดงมุมมองการตรวจสอบสิทธิ์หากผู้ใช้ยังไม่ได้ตกลง
โปรดทราบว่าการใช้เครื่องมือสำหรับนักพัฒนา Spotify แสดงว่าคุณยอมรับข้อกำหนดการใช้งานสำหรับนักพัฒนาของเรา
บทช่วยสอนนี้จะอธิบายให้คุณทราบทีละขั้นตอนในการสร้างแอปง่ายๆ ที่ใช้ Spotify iOS SDK เพื่อเล่นแทร็กเสียงและสมัครรับสถานะผู้เล่น มันจะเดินผ่านขั้นตอนการอนุญาต
ทำตามขั้นตอนเหล่านี้เพื่อให้แน่ใจว่าคุณพร้อมที่จะเริ่มเขียนโค้ด
เพิ่มแพ็คเกจ SpotifyiOS ให้กับโปรเจ็กต์ของคุณ คุณสามารถทำได้ผ่าน Swift Package Manager (SPM) หรือโดยการเพิ่ม SpotifyiOS.xcframework ไปยังโปรเจ็กต์ Xcode ของคุณโดยตรง
ใน info.plist ของคุณ ให้เพิ่ม URI การเปลี่ยนเส้นทางที่คุณลงทะเบียนไว้ที่แอปพลิเคชันของฉัน คุณจะต้องเพิ่ม URI การเปลี่ยนเส้นทางของคุณใต้ "ประเภท URL" และ "แบบแผน URL" อย่าลืมตั้งค่า "ตัวระบุ URL" ที่ไม่ซ้ำกันด้วย
เพิ่มไลบรารีลงในไฟล์ต้นฉบับของคุณ
สวิฟท์
import SpotifyiOSวัตถุประสงค์-ค
# import < SpotifyiOS/SpotifyiOS.h > เพื่อให้สามารถใช้ส่วนควบคุมการเล่นของ SDK ได้ ผู้ใช้จำเป็นต้องอนุญาตแอปพลิเคชันของคุณ หากไม่เป็นเช่นนั้น การเชื่อมต่อจะล้มเหลวโดยมีข้อผิดพลาด No token provided หากต้องการอนุญาตให้ผู้ใช้ให้สิทธิ์แอปของคุณ คุณสามารถใช้ขั้นตอนการให้สิทธิ์ในตัวได้
เริ่มต้น SPTConfiguration ด้วย ID ไคลเอนต์ของคุณและเปลี่ยนเส้นทาง URI
สวิฟท์
let configuration = SPTConfiguration (
clientID : " YOUR_CLIENT_ID " ,
redirectURL : URL ( string : " your_redirect_uri " ) !
)วัตถุประสงค์-ค
SPTConfiguration *configuration = [[SPTConfiguration alloc ] initWithClientID: @" your_client_id "
redirectURL: [ NSURL URLWithString: @" your_redirect_uri " ]]; เริ่มต้น SPTAppRemote ด้วย SPTConfiguration ของคุณ
สวิฟท์
self . appRemote = SPTAppRemote ( configuration : configuration , logLevel : . debug )วัตถุประสงค์-ค
self.appRemote = [[SPTAppRemote alloc ] initWithConfiguration: configuration logLevel: SPTAppRemoteLogLevelDebug];เริ่มต้นขั้นตอนการรับรองความถูกต้อง (สำหรับวิธีอื่นในการตรวจสอบว่ามีการติดตั้ง Spotify หรือไม่ รวมถึงการระบุแหล่งที่มาของการติดตั้ง โปรดดูคู่มือการเชื่อมโยงเนื้อหาของเรา)
สวิฟท์
// Note: A blank string will play the user's last song or pick a random one.
self . appRemote . authorizeAndPlayURI ( " spotify:track:69bp2EbF7Q2rqc5N3ylezZ " ) { spotifyInstalled in
if !spotifyInstalled {
/*
* The Spotify app is not installed.
* Use SKStoreProductViewController with [SPTAppRemote spotifyItunesItemIdentifier] to present the user
* with a way to install the Spotify app.
*/
}
}วัตถุประสงค์-ค
// Note: A blank string will play the user's last song or pick a random one.
[ self .appRemote authorizeAndPlayURI: @" spotify:track:69bp2EbF7Q2rqc5N3ylezZ " completionHandler: ^( BOOL spotifyInstalled) {
if (!spotifyInstalled) {
/*
* The Spotify app is not installed.
* Use SKStoreProductViewController with [SPTAppRemote spotifyItunesItemIdentifier] to present the user
* with a way to install the Spotify app.
*/
}
}]; กำหนดค่า AppDelegate ของคุณเพื่อแยกวิเคราะห์ accessToken ใน application:openURL:options: และตั้งค่าบนพารามิเตอร์การเชื่อมต่อ SPTAppRemote
วัตถุประสงค์-ค
- ( BOOL )application:(UIApplication *)app openURL:( NSURL *)url options:( NSDictionary <UIApplicationOpenURLOptionsKey, id > *)options
{
NSDictionary *params = [ self .appRemote authorizationParametersFromURL: url];
NSString *token = params[SPTAppRemoteAccessTokenKey];
if (token) {
self. appRemote . connectionParameters . accessToken = token;
} else if (params[SPTAppRemoteErrorDescriptionKey]) {
NSLog ( @" %@ " , params[SPTAppRemoteErrorDescriptionKey]);
}
return YES ;
}หากคุณใช้ UIScene คุณจะต้องใช้วิธีการที่เหมาะสมกับตัวแทนฉากของคุณ
สวิฟท์
func scene ( _ scene : UIScene , openURLContexts URLContexts : Set < UIOpenURLContext > ) {
guard let url = URLContexts . first ? . url else {
return
}
let parameters = appRemote . authorizationParameters ( from : url ) ;
if let access_token = parameters ? [ SPTAppRemoteAccessTokenKey ] {
appRemote . connectionParameters . accessToken = access_token
self . accessToken = access_token
} else if let error_description = parameters ? [ SPTAppRemoteErrorDescriptionKey ] {
// Show the error
}
}ตั้งค่าผู้รับมอบสิทธิ์การเชื่อมต่อของคุณและพยายามเชื่อมต่อ
สวิฟท์
self . appRemote . delegate = self
self . appRemote . connect ( ) // MARK: AppRemoteDelegate
func appRemoteDidEstablishConnection ( _ appRemote : SPTAppRemote ) {
// Connection was successful, you can begin issuing commands
}
func appRemote ( _ appRemote : SPTAppRemote , didFailConnectionAttemptWithError error : Error ? ) {
// Connection failed
}
func appRemote ( _ appRemote : SPTAppRemote , didDisconnectWithError error : Error ? ) {
// Connection disconnected
}วัตถุประสงค์-ค
self.appRemote.delegate = self;
[ self .appRemote connect ];- ( void )appRemoteDidEstablishConnection:(SPTAppRemote *)appRemote
{
// Connection was successful, you can begin issuing commands
}
- ( void )appRemote:(SPTAppRemote *)appRemote didFailConnectionAttemptWithError:( NSError *)error
{
// Connection failed
}
- ( void )appRemote:(SPTAppRemote *)appRemote didDisconnectWithError:(nullable NSError *)error
{
// Connection disconnected
}ตั้งค่าผู้รับมอบสิทธิ์และสมัครสมาชิกสถานะผู้เล่น:
สวิฟท์
self . appRemote . playerAPI ? . delegate = self
appRemote . playerAPI ? . subscribe ( toPlayerState : { result , error in
// Handle Errors
} ) // MARK: SPTAppRemotePlayerStateDelegate
func playerStateDidChange ( _ playerState : SPTAppRemotePlayerState ) {
print ( " track name ( playerState . track . name ) " )
}วัตถุประสงค์-ค
appRemote.playerAPI.delegate = self;
[appRemote.playerAPI subscribeToPlayerState: ^( id _Nullable result, NSError * _Nullable error) {
// Handle Errors
}];- ( void )playerStateDidChange:( id <SPTAppRemotePlayerState>)playerState
{
NSLog ( @" Track name: %@ " , playerState. track . name );
}ตามมารยาท คุณควรยกเลิกการเชื่อมต่อ App Remote เสมอเมื่อแอปของคุณเข้าสู่สถานะเบื้องหลัง สิ่งนี้จะบอก Spotify ว่าสามารถปิดการใช้งานสตรีมที่ใช้งานอยู่ได้อย่างปลอดภัย หากแอปของคุณเรียกการยกเลิกการเชื่อมต่อไม่ถูกต้อง Spotify ไม่มีทางรู้ได้ว่าไม่ควรรักษาการเชื่อมต่อไว้ และอาจส่งผลให้เกิดปัญหาการเชื่อมต่อในอนาคต
หากคุณต้องการให้แอปของคุณเชื่อมต่อใหม่โดยอัตโนมัติหลังจากเหตุการณ์หยุดชะงัก เช่น สายเรียกเข้าหรือการโต้ตอบกับ Siri คุณสามารถใช้การโทรกลับ willResignActive และ didBecomeActive เพื่อยกเลิกการเชื่อมต่อและเชื่อมต่อใหม่อย่างปลอดภัย หากคุณไม่ต้องการเชื่อมต่อใหม่โดยตรง โดยทั่วไปการปิดการเชื่อมต่อในการเรียกกลับ didEnterBackground ก็เพียงพอแล้ว
สวิฟท์
func sceneWillResignActive ( _ scene : UIScene ) {
self . appRemote . disconnect ( )
}
func sceneDidBecomeActive ( _ scene : UIScene ) {
self . appRemote . connect ( )
}วัตถุประสงค์-ค
- ( void )applicationWillResignActive:(UIApplication *)application
{
[ self .appRemote disconnect ];
}
- ( void )applicationDidBecomeActive:(UIApplication *)application
{
[ self .appRemote connect ];
}
// If you're using UIWindowSceneDelegate
- ( void )sceneDidBecomeActive:(UIScene *)scene
{
[ self .appRemote connect ];
}
- ( void )sceneWillResignActive:(UIScene *)scene
{
[ self .appRemote disconnect ];
} เหตุใดจึงต้องเล่นเพลงเพื่อเชื่อมต่อกับ SPTAppRemote
จะต้องเล่นเพลงเมื่อคุณเชื่อมต่อกับ SPTAppRemote เพื่อให้แน่ใจว่าแอป Spotify จะไม่ถูกระงับในเบื้องหลัง แอปพลิเคชัน iOS สามารถทำงานได้ในเบื้องหลังเพียงไม่กี่วินาที เว้นแต่ว่าแอปพลิเคชันเหล่านั้นกำลังดำเนินการบางอย่าง เช่น การนำทางหรือเล่นเพลง
เธรด SpotifyiOS.framework ปลอดภัยหรือไม่
ไม่ ขณะนี้เฟรมเวิร์กคาดว่าจะถูกเรียกจากเธรดหลัก มันจะถ่ายงานส่วนใหญ่ไปยังเธรดพื้นหลังภายใน แต่การเรียกกลับไปยังโค้ดของคุณก็จะเกิดขึ้นบนเธรดหลักด้วย
จะทำอย่างไรหากฉันต้องอนุญาตโดยไม่เริ่มเล่น?
มีวิธีอื่นในการอนุญาต คุณสามารถหาข้อมูลเพิ่มเติมเกี่ยวกับเรื่องนี้ได้ที่นี่
