ios sdk
v3.0.0
Le framework Spotify iOS permet à votre application d'interagir avec l'application Spotify exécutée en arrière-plan sur l'appareil d'un utilisateur. Les fonctionnalités incluent l'autorisation, l'obtention de métadonnées pour la piste et le contexte en cours de lecture, ainsi que l'émission de commandes de lecture.
Remarque : en utilisant les outils de développement Spotify, vous acceptez nos conditions d'utilisation pour les développeurs.
Le SDK Spotify iOS est un ensemble d'objets légers qui se connectent à l'application Spotify et vous permettent de la contrôler pendant que toute la lourde tâche de lecture est déchargée sur l'application Spotify elle-même. L'application Spotify s'occupe de la lecture, de la mise en réseau, de la mise en cache hors ligne et de l'intégration musicale du système d'exploitation, vous laissant vous concentrer sur votre expérience utilisateur. Passer de votre application à l'application Spotify et vice versa est une expérience simplifiée où la lecture et les métadonnées restent toujours synchronisées.
Principales fonctionnalités
Dépôt de bogues
Composants
Comment fonctionnent les appels à distance via l'application ?
Conditions d'utilisation
Tutoriel
Foire aux questions
Nous aimons les commentaires de la communauté des développeurs, alors n'hésitez pas à signaler les fonctionnalités manquantes ou les bogues sur notre outil de suivi des problèmes. Assurez-vous de rechercher les problèmes existants avant d’en créer de nouveaux.
Billets de bug ouverts | Demandes de fonctionnalités ouvertes
Le framework Spotify iOS nécessite une cible de déploiement iOS 12 ou supérieur. Les architectures suivantes sont prises en charge dans le SDK :
SPTAppRemoteAlbumSPTAppRemoteArtistSPTAppRemoteLibraryStateSPTAppRemotePlaybackRestrictionsSPTAppRemotePlaybackOptionsSPTAppRemotePlayerStateSPTAppRemoteTrackSPTAppRemoteContentItemSPTAppRemoteUserCapabilitiesSPTAppRemoteImageRepresentableSPTConfigurationLe point d'entrée principal pour se connecter à l'application Spotify et récupérer les composants de l'API. Utilisez-le pour établir, surveiller et mettre fin à la connexion.
Envoyez des commandes liées à la lecture telles que :
Récupérer une image pour un SPTAppRemoteImageRepresentable
Récupérer/s'abonner/définir des données relatives à l'utilisateur telles que :
SPTAppRemoteUserCapabilitiesRécupérez le contenu recommandé pour l’utilisateur.
Lorsque vous interagissez avec l'une des API App Remote, vous transmettez un bloc SPTAppRemoteCallback qui est invoqué soit avec l'élément de résultat attendu, soit avec une NSError si l'opération échoue. Le blocage est déclenché après la réception de la commande par l'application Spotify (ou si la connexion n'a pas pu être établie).
Voici un exemple utilisant SPTRemotePlayerAPI pour sauter une chanson :
[appRemote.playerAPI skipToNext: ^( id _Nullable result, NSError * _Nullable error) {
if (error) {
// Operation failed
} else {
// Operation succeeded
}
}];Nous fournissons quelques exemples de projets pour vous aider à démarrer avec le framework iOS dans le dossier DemoProjects. Consultez le fichier Readme dans le dossier DemoProjects pour plus d’informations sur le rôle de chaque exemple.
Pour communiquer avec l'application Spotify, votre application devra d'abord obtenir l'autorisation d'un utilisateur pour contrôler la lecture en utilisant l'autorisation intégrée pour App Remote. Pour ce faire, vous devrez demander une vue d'autorisation lors de la connexion à Spotify. Le framework demandera automatiquement la portée de app-remote-control et affichera la vue d'authentification si l'utilisateur ne l'a pas encore accepté.
Notez qu'en utilisant les outils de développement Spotify, vous acceptez nos conditions d'utilisation pour les développeurs.
Ce didacticiel vous guide étape par étape dans la création d'une application simple qui utilise le SDK Spotify iOS pour lire une piste audio et s'abonner à l'état du lecteur. Il parcourra le flux d’autorisation.
Suivez ces étapes pour vous assurer que vous êtes prêt à commencer à coder.
Ajoutez le package SpotifyiOS à votre projet. Vous pouvez le faire via Swift Package Manager (SPM) ou en ajoutant directement SpotifyiOS.xcframework à votre projet Xcode.
Dans votre info.plist, ajoutez votre URI de redirection que vous avez enregistré dans Mes applications. Vous devrez ajouter votre URI de redirection sous « Types d'URL » et « Schémas d'URL ». Assurez-vous également de définir un « identifiant d'URL » unique.
Ajoutez la bibliothèque à vos fichiers sources.
Rapide
import SpotifyiOSObjectif-c
# import < SpotifyiOS/SpotifyiOS.h > Pour pouvoir utiliser la partie contrôle de lecture du SDK, l'utilisateur doit autoriser votre application. Si ce n’est pas le cas, la connexion échouera avec une erreur No token provided . Pour permettre à l'utilisateur d'autoriser votre application, vous pouvez utiliser le flux d'autorisation intégré.
Initialisez SPTConfiguration avec votre ID client et redirigez l'URI.
Rapide
let configuration = SPTConfiguration (
clientID : " YOUR_CLIENT_ID " ,
redirectURL : URL ( string : " your_redirect_uri " ) !
)Objectif-c
SPTConfiguration *configuration = [[SPTConfiguration alloc ] initWithClientID: @" your_client_id "
redirectURL: [ NSURL URLWithString: @" your_redirect_uri " ]]; Initialisez SPTAppRemote avec votre SPTConfiguration
Rapide
self . appRemote = SPTAppRemote ( configuration : configuration , logLevel : . debug )Objectif-c
self.appRemote = [[SPTAppRemote alloc ] initWithConfiguration: configuration logLevel: SPTAppRemoteLogLevelDebug];Lancez le flux d'authentification (pour d'autres moyens de détecter si Spotify est installé, ainsi que d'attribuer les installations, veuillez consulter notre Guide de liaison de contenu).
Rapide
// 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.
*/
}
}Objectif-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.
*/
}
}]; Configurez votre AppDelegate pour analyser le accessToken dans application:openURL:options: et définissez-le sur les paramètres de connexion SPTAppRemote .
Objectif-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 ;
}Si vous utilisez UIScene, vous devez utiliser la méthode appropriée dans votre délégué de scène.
Rapide
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
}
}Définissez votre délégué de connexion et essayez de vous connecter.
Rapide
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
}Objectif-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
}Définissez un délégué et abonnez-vous à l'état du joueur :
Rapide
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 ) " )
}Objectif-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 );
}Par courtoisie, vous devez toujours déconnecter App Remote lorsque votre application passe en arrière-plan. Cela indique à Spotify qu'il est possible de désactiver le flux actif en toute sécurité. Si votre application n'appelle pas correctement la déconnexion, Spotify n'a aucun moyen de savoir qu'elle ne doit pas maintenir la connexion, ce qui peut entraîner de futurs problèmes de connexion.
Si vous souhaitez que votre application se reconnecte automatiquement après des événements de perturbation tels que des appels entrants ou des interactions Siri, vous pouvez utiliser les rappels willResignActive et didBecomeActive pour vous déconnecter et vous reconnecter en toute sécurité. Si vous ne souhaitez pas vous reconnecter directement, il suffit généralement de fermer la connexion dans les rappels didEnterBackground .
Rapide
func sceneWillResignActive ( _ scene : UIScene ) {
self . appRemote . disconnect ( )
}
func sceneDidBecomeActive ( _ scene : UIScene ) {
self . appRemote . connect ( )
}Objectif-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 ];
} Pourquoi la musique doit-elle être diffusée pour se connecter à SPTAppRemote ?
La musique doit être diffusée lorsque vous vous connectez à SPTAppRemote pour garantir que l'application Spotify n'est pas suspendue en arrière-plan. Les applications iOS ne peuvent rester actives en arrière-plan que pendant quelques secondes, à moins qu'elles n'effectuent activement quelque chose comme la navigation ou la lecture de musique.
Le thread SpotifyiOS.framework est-il sécurisé ?
Non, le framework s'attend actuellement à être appelé depuis le thread principal. Il déchargera la plupart de son travail sur un thread d'arrière-plan en interne, mais les rappels de votre code se produiront également sur le thread principal.
Que faire si je dois autoriser sans démarrer la lecture ?
Il existe une méthode d'autorisation alternative. Vous pouvez trouver plus d’informations à ce sujet ici.
