ios sdk
v3.0.0
Das Spotify iOS-Framework ermöglicht Ihrer Anwendung die Interaktion mit der Spotify-App, die im Hintergrund auf dem Gerät eines Benutzers ausgeführt wird. Zu den Funktionen gehören die Autorisierung, das Abrufen von Metadaten für den aktuell wiedergegebenen Titel und Kontext sowie das Erteilen von Wiedergabebefehlen.
Bitte beachten Sie: Durch die Nutzung der Spotify-Entwicklertools akzeptieren Sie unsere Nutzungsbedingungen für Entwickler.
Das Spotify iOS SDK besteht aus einer Reihe leichter Objekte, die sich mit der Spotify-App verbinden und Ihnen die Steuerung ermöglichen, während die ganze schwere Arbeit der Wiedergabe auf die Spotify-App selbst verlagert wird. Die Spotify-App kümmert sich um Wiedergabe, Netzwerk, Offline-Caching und OS-Musikintegration, sodass Sie sich auf Ihr Benutzererlebnis konzentrieren können. Der Wechsel von Ihrer App zur Spotify-App und umgekehrt ist ein optimiertes Erlebnis, bei dem Wiedergabe und Metadaten immer synchron bleiben.
Hauptmerkmale
Fehler melden
Komponenten
Wie funktionieren App-Fernanrufe?
Nutzungsbedingungen
Anleitung
Häufig gestellte Fragen
Wir freuen uns über Feedback aus der Entwickler-Community. Melden Sie uns daher gerne fehlende Funktionen oder Fehler in unserem Issue-Tracker. Stellen Sie sicher, dass Sie vorhandene Probleme durchsuchen, bevor Sie neue erstellen.
Bug-Tickets öffnen | Offene Funktionsanfragen
Das Spotify iOS-Framework erfordert ein Bereitstellungsziel von iOS 12 oder höher. Die folgenden Architekturen werden im SDK unterstützt:
SPTAppRemoteAlbumSPTAppRemoteArtistSPTAppRemoteLibraryStateSPTAppRemotePlaybackRestrictionsSPTAppRemotePlaybackOptionsSPTAppRemotePlayerStateSPTAppRemoteTrackSPTAppRemoteContentItemSPTAppRemoteUserCapabilitiesSPTAppRemoteImageRepresentableSPTConfigurationDer Haupteinstiegspunkt zum Herstellen einer Verbindung zur Spotify-App und zum Abrufen von API-Komponenten. Hiermit können Sie die Verbindung aufbauen, überwachen und beenden.
Senden Sie wiedergabebezogene Befehle wie:
Rufen Sie ein Bild für ein SPTAppRemoteImageRepresentable ab
Benutzerbezogene Daten abrufen/abonnieren/einstellen, wie zum Beispiel:
SPTAppRemoteUserCapabilities ab und/oder abonnieren Sie esRufen Sie empfohlene Inhalte für den Benutzer ab.
Wenn Sie mit einer der App Remote-APIs interagieren, übergeben Sie einen SPTAppRemoteCallback -Block, der entweder mit dem erwarteten Ergebniselement oder einem NSError aufgerufen wird, wenn der Vorgang fehlgeschlagen ist. Die Sperrung wird ausgelöst, nachdem der Befehl von der Spotify-App empfangen wurde (oder wenn die Verbindung nicht hergestellt werden konnte).
Hier ist ein Beispiel für die Verwendung der SPTRemotePlayerAPI zum Überspringen eines Lieds:
[appRemote.playerAPI skipToNext: ^( id _Nullable result, NSError * _Nullable error) {
if (error) {
// Operation failed
} else {
// Operation succeeded
}
}];Im Ordner „DemoProjects“ stellen wir einige Beispielprojekte bereit, die Ihnen den Einstieg in das iOS Framework erleichtern sollen. Weitere Informationen zu den einzelnen Beispielen finden Sie in der Readme-Datei im Ordner „DemoProjects“.
Um mit der Spotify-App zu kommunizieren, muss Ihre Anwendung zunächst die Berechtigung eines Benutzers zur Steuerung der Wiedergabe einholen, indem Sie die integrierte Autorisierung für App Remote verwenden. Dazu müssen Sie bei der Verbindung mit Spotify eine Autorisierungsansicht anfordern. Das Framework fordert automatisch den app-remote-control -Bereich an und zeigt die Authentifizierungsansicht an, wenn der Benutzer dem noch nicht zugestimmt hat.
Beachten Sie, dass Sie durch die Nutzung der Spotify-Entwicklertools unsere Nutzungsbedingungen für Entwickler akzeptieren.
Dieses Tutorial führt Sie Schritt für Schritt durch die Erstellung einer einfachen App, die das Spotify iOS SDK verwendet, um einen Audiotrack abzuspielen und den Player-Status zu abonnieren. Der Autorisierungsablauf wird durchlaufen.
Befolgen Sie diese Schritte, um sicherzustellen, dass Sie für den Beginn des Codierens vorbereitet sind.
Fügen Sie das SpotifyiOS-Paket zu Ihrem Projekt hinzu. Sie können dies entweder über den Swift Package Manager (SPM) tun oder indem Sie SpotifyiOS.xcframework direkt zu Ihrem Xcode-Projekt hinzufügen.
Fügen Sie in Ihrer info.plist Ihren Weiterleitungs-URI hinzu, den Sie unter „Meine Anwendungen“ registriert haben. Sie müssen Ihren Weiterleitungs-URI unter „URL-Typen“ und „URL-Schemata“ hinzufügen. Stellen Sie sicher, dass Sie auch eine eindeutige „URL-ID“ festlegen.
Fügen Sie die Bibliothek zu Ihren Quelldateien hinzu.
Schnell
import SpotifyiOSZiel-c
# import < SpotifyiOS/SpotifyiOS.h > Um den Wiedergabesteuerungsteil des SDK verwenden zu können, muss der Benutzer Ihre Anwendung autorisieren. Ist dies nicht der Fall, schlägt die Verbindung mit der Fehlermeldung No token provided fehl. Um dem Benutzer die Autorisierung Ihrer App zu ermöglichen, können Sie den integrierten Autorisierungsablauf verwenden.
Initialisieren Sie SPTConfiguration mit Ihrer Client-ID und dem Umleitungs-URI.
Schnell
let configuration = SPTConfiguration (
clientID : " YOUR_CLIENT_ID " ,
redirectURL : URL ( string : " your_redirect_uri " ) !
)Ziel-c
SPTConfiguration *configuration = [[SPTConfiguration alloc ] initWithClientID: @" your_client_id "
redirectURL: [ NSURL URLWithString: @" your_redirect_uri " ]]; Initialisieren Sie SPTAppRemote mit Ihrer SPTConfiguration
Schnell
self . appRemote = SPTAppRemote ( configuration : configuration , logLevel : . debug )Ziel-c
self.appRemote = [[SPTAppRemote alloc ] initWithConfiguration: configuration logLevel: SPTAppRemoteLogLevelDebug];Starten Sie den Authentifizierungsfluss (weitere Möglichkeiten zur Erkennung, ob Spotify installiert ist, sowie zur Zuordnung von Installationen finden Sie in unserem Leitfaden zur Inhaltsverknüpfung).
Schnell
// 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.
*/
}
}Ziel-c
// 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.
*/
}
}]; Konfigurieren Sie Ihr AppDelegate so, dass das accessToken in application:openURL:options: analysiert wird, und legen Sie es auf den SPTAppRemote -Verbindungsparametern fest.
Ziel-c
- ( 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 ;
}Wenn Sie UIScene verwenden, müssen Sie in Ihrem Szenendelegaten die entsprechende Methode verwenden.
Schnell
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
}
}Legen Sie Ihren Verbindungsdelegierten fest und versuchen Sie, eine Verbindung herzustellen.
Schnell
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
}Ziel-c
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
}Legen Sie einen Delegaten fest und abonnieren Sie den Spielerstatus:
Schnell
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 ) " )
}Ziel-c
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 );
}Aus Höflichkeitsgründen sollten Sie App Remote immer trennen, wenn Ihre App in den Hintergrundzustand wechselt. Dies teilt Spotify mit, dass es sicher ist, den aktiven Stream zu deaktivieren. Wenn Ihre App „Disconnect“ nicht ordnungsgemäß aufruft, kann Spotify nicht erkennen, dass die Verbindung nicht aufrechterhalten werden soll, und dies kann in Zukunft zu Verbindungsproblemen führen.
Wenn Sie möchten, dass Ihre App nach Unterbrechungsereignissen wie eingehenden Anrufen oder Siri-Interaktionen automatisch die Verbindung wiederherstellt, können Sie die Rückrufe willResignActive und didBecomeActive verwenden, um die Verbindung sicher zu trennen und wieder herzustellen. Wenn Sie die Verbindung nicht direkt wiederherstellen möchten, reicht es normalerweise aus, die Verbindung in didEnterBackground Rückrufen zu schließen.
Schnell
func sceneWillResignActive ( _ scene : UIScene ) {
self . appRemote . disconnect ( )
}
func sceneDidBecomeActive ( _ scene : UIScene ) {
self . appRemote . connect ( )
}Ziel-c
- ( 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 ];
} Warum muss Musik abgespielt werden, um eine Verbindung mit SPTAppRemote herzustellen?
Wenn Sie eine Verbindung mit SPTAppRemote herstellen, muss Musik abgespielt werden, um sicherzustellen, dass die Spotify-App nicht im Hintergrund angehalten wird. iOS-Anwendungen können nur wenige Sekunden im Hintergrund aktiv bleiben, es sei denn, sie führen aktiv etwas wie Navigation oder Musikwiedergabe aus.
Ist der SpotifyiOS.framework-Thread sicher?
Nein, das Framework erwartet derzeit, vom Hauptthread aufgerufen zu werden. Der Großteil der Arbeit wird intern an einen Hintergrundthread verlagert, Rückrufe an Ihren Code erfolgen jedoch auch im Hauptthread.
Was passiert, wenn ich eine Autorisierung durchführen muss, ohne die Wiedergabe zu starten?
Es gibt eine alternative Autorisierungsmethode. Weitere Informationen dazu finden Sie hier.
