ios sdk
v3.0.0
A estrutura do Spotify iOS permite que seu aplicativo interaja com o aplicativo Spotify em execução em segundo plano no dispositivo de um usuário. Os recursos incluem autorização, obtenção de metadados para a faixa e contexto atualmente reproduzidos, bem como emissão de comandos de reprodução.
Observação: ao usar as ferramentas de desenvolvedor do Spotify, você aceita nossos Termos de uso do desenvolvedor.
O Spotify iOS SDK é um conjunto de objetos leves que se conectam ao aplicativo Spotify e permitem controlá-lo enquanto todo o trabalho pesado da reprodução é transferido para o próprio aplicativo Spotify. O aplicativo Spotify cuida da reprodução, rede, cache offline e integração de música do sistema operacional, deixando você se concentrar na experiência do usuário. Mudar do seu aplicativo para o aplicativo Spotify e vice-versa é uma experiência simplificada onde a reprodução e os metadados permanecem sempre sincronizados.
Principais recursos
Arquivando Bugs
Componentes
Como funcionam as chamadas remotas de aplicativos?
Termos de Uso
Tutorial
Perguntas frequentes
Adoramos o feedback da comunidade de desenvolvedores, então sinta-se à vontade para registrar recursos ausentes ou bugs em nosso rastreador de problemas. Certifique-se de pesquisar os problemas existentes antes de criar novos.
Abrir tickets de bug | Abrir solicitações de recursos
A estrutura do Spotify iOS requer um destino de implantação do iOS 12 ou superior. As seguintes arquiteturas são suportadas no SDK:
SPTAppRemoteAlbumSPTAppRemoteArtistSPTAppRemoteLibraryStateSPTAppRemotePlaybackRestrictionsSPTAppRemotePlaybackOptionsSPTAppRemotePlayerStateSPTAppRemoteTrackSPTAppRemoteContentItemSPTAppRemoteUserCapabilitiesSPTAppRemoteImageRepresentableSPTConfigurationO principal ponto de entrada para conectar-se ao aplicativo Spotify e recuperar componentes da API. Use isso para estabelecer, monitorar e encerrar a conexão.
Envie comandos relacionados à reprodução, como:
Buscar uma imagem para um SPTAppRemoteImageRepresentable
Buscar/inscrever/definir dados relacionados ao usuário, como:
SPTAppRemoteUserCapabilitiesBusque conteúdo recomendado para o usuário.
Ao interagir com qualquer uma das APIs do App Remote, você passa um bloco SPTAppRemoteCallback que é invocado com o item de resultado esperado ou um NSError se a operação falhar. O bloqueio é acionado após o comando ser recebido pelo app Spotify (ou caso não seja possível estabelecer a conexão).
Aqui está um exemplo usando SPTRemotePlayerAPI para pular uma música:
[appRemote.playerAPI skipToNext: ^( id _Nullable result, NSError * _Nullable error) {
if (error) {
// Operation failed
} else {
// Operation succeeded
}
}];Fornecemos alguns projetos de amostra para ajudá-lo a começar a usar o iOS Framework na pasta DemoProjects. Consulte o Leiame na pasta DemoProjects para obter mais informações sobre o que cada amostra faz.
Para se comunicar com o aplicativo Spotify, seu aplicativo precisará primeiro obter permissão do usuário para controlar a reprodução usando a autorização integrada do App Remote. Para fazer isso, você precisará solicitar autorização de visualização ao se conectar ao Spotify. A estrutura solicitará automaticamente o escopo app-remote-control e mostrará a visualização de autenticação se o usuário ainda não tiver concordado com isso.
Observe que ao usar as ferramentas de desenvolvedor do Spotify, você aceita nossos Termos de Uso do Desenvolvedor.
Este tutorial orienta você passo a passo na criação de um aplicativo simples que usa o SDK do Spotify iOS para reproduzir uma faixa de áudio e assinar o estado do player. Ele percorrerá o fluxo de autorização.
Siga estas etapas para se certificar de que está preparado para começar a codificar.
Adicione o pacote SpotifyiOS ao seu projeto. Você pode fazer isso através do Swift Package Manager (SPM) ou adicionando SpotifyiOS.xcframework diretamente ao seu projeto Xcode.
Em seu info.plist adicione seu URI de redirecionamento que você registrou em Meus Aplicativos. Você precisará adicionar seu URI de redirecionamento em "Tipos de URL" e "Esquemas de URL". Certifique-se de definir também um "identificador de URL" exclusivo.
Adicione a biblioteca aos seus arquivos de origem.
Rápido
import SpotifyiOSObjetivo-c
# import < SpotifyiOS/SpotifyiOS.h > Para poder usar a parte de controle de reprodução do SDK, o usuário precisa autorizar seu aplicativo. Caso contrário, a conexão falhará com um erro No token provided . Para permitir que o usuário autorize seu aplicativo, você pode usar o fluxo de autorização integrado.
Inicialize SPTConfiguration com seu ID de cliente e redirecione o URI.
Rápido
let configuration = SPTConfiguration (
clientID : " YOUR_CLIENT_ID " ,
redirectURL : URL ( string : " your_redirect_uri " ) !
)Objetivo-c
SPTConfiguration *configuration = [[SPTConfiguration alloc ] initWithClientID: @" your_client_id "
redirectURL: [ NSURL URLWithString: @" your_redirect_uri " ]]; Inicialize SPTAppRemote com seu SPTConfiguration
Rápido
self . appRemote = SPTAppRemote ( configuration : configuration , logLevel : . debug )Objetivo-c
self.appRemote = [[SPTAppRemote alloc ] initWithConfiguration: configuration logLevel: SPTAppRemoteLogLevelDebug];Inicie o fluxo de autenticação (para outras maneiras de detectar se o Spotify está instalado, bem como atribuir instalações, consulte nosso Guia de vinculação de conteúdo).
Rápido
// 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.
*/
}
}Objetivo-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.
*/
}
}]; Configure seu AppDelegate para analisar o accessToken em application:openURL:options: e defina-o em SPTAppRemote connectionParameters.
Objetivo-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 ;
}Se você estiver usando o UIScene, precisará usar o método apropriado em seu delegado de cena.
Rápido
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
}
}Defina seu delegado de conexão e tente conectar-se.
Rápido
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
}Objetivo-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
}Defina um delegado e assine o estado do jogador:
Rápido
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 ) " )
}Objetivo-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 );
}Como cortesia, você deve sempre desconectar o App Remote quando seu aplicativo entrar em segundo plano. Isso informa ao Spotify que é seguro desativar o stream ativo. Se o seu aplicativo não ligar corretamente, o Spotify não tem como saber que não deve manter a conexão, e isso pode resultar em problemas futuros de conexão.
Se quiser que seu aplicativo se reconecte automaticamente após eventos de interrupção, como chamadas recebidas ou interações com Siri, você pode usar os retornos de chamada willResignActive e didBecomeActive para desconectar e reconectar com segurança. Se você não deseja se reconectar diretamente, normalmente é suficiente fechar a conexão em retornos de chamada didEnterBackground .
Rápido
func sceneWillResignActive ( _ scene : UIScene ) {
self . appRemote . disconnect ( )
}
func sceneDidBecomeActive ( _ scene : UIScene ) {
self . appRemote . connect ( )
}Objetivo-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 ];
} Por que a música precisa estar tocando para se conectar ao SPTAppRemote ?
A música deve estar tocando quando você se conecta ao SPTAppRemote para garantir que o aplicativo Spotify não seja suspenso em segundo plano. Os aplicativos iOS só podem permanecer ativos em segundo plano por alguns segundos, a menos que estejam ativamente fazendo algo como navegação ou reprodução de música.
O thread SpotifyiOS.framework é seguro?
Não, a estrutura atualmente espera ser chamada a partir do thread principal. Ele descarregará internamente a maior parte de seu trabalho para um thread em segundo plano, mas os retornos de chamada para o seu código também ocorrerão no thread principal.
E se eu precisar autorizar sem iniciar a reprodução?
Existe um método de autorização alternativo. Você pode encontrar mais informações sobre isso aqui.
