SPTAuth Class Reference
Inherits from | NSObject |
Declared in | SPTAuth.h |
Overview
This class provides helper methods for authenticating users against the Spotify OAuth authentication service.
Tasks
Convenience Getters
Environment settings
-
clientID
property -
redirectURL
property -
requestedScopes
property -
session
property -
sessionUserDefaultsKey
property -
tokenSwapURL
property -
tokenRefreshURL
property -
hasTokenSwapService
property -
hasTokenRefreshService
property
Starting Authentication
-
+ loginURLForClientId:withRedirectURL:scopes:responseType:
-
+ loginURLForClientId:withRedirectURL:scopes:responseType:campaignId:
Handling Authentication Callback URLs
-
– spotifyWebAuthenticationURL
-
– spotifyAppAuthenticationURL
-
– canHandleURL:
-
– handleAuthCallbackWithTriggeredAuthURL:callback:
-
+ supportsApplicationAuthentication
-
+ spotifyApplicationIsInstalled
Renewing Sessions
Properties
hasTokenRefreshService
Returns true if there’s a valid token refresh url specified.
@property (readonly) BOOL hasTokenRefreshService
Declared In
SPTAuth.h
hasTokenSwapService
Returns true if there’s a valid token swap url specified.
@property (readonly) BOOL hasTokenSwapService
Declared In
SPTAuth.h
redirectURL
Your redirect URL.
@property (strong, readwrite) NSURL *redirectURL
Declared In
SPTAuth.h
requestedScopes
Required scopes for the app, used by authentication steps
@property (strong, readwrite) NSArray *requestedScopes
Declared In
SPTAuth.h
session
The current session, Note: setting this will persist it in NSUserDefaults standardUserDefaults
if
a sessionUserDefaultsKey
is set.
@property (strong, readwrite) SPTSession *session
Declared In
SPTAuth.h
sessionUserDefaultsKey
User defaults key, if you want to automatically save the session from user defaults when it changes.
@property (strong, readwrite) NSString *sessionUserDefaultsKey
Declared In
SPTAuth.h
Class Methods
defaultInstance
Returns a pre-created SPTAuth
instance for convenience.
+ (SPTAuth *)defaultInstance
Return Value
A pre-created default SPTAuth
instance.
Declared In
SPTAuth.h
loginURLForClientId:withRedirectURL:scopes:responseType:
Returns a URL that, when opened, will begin the Spotify authentication process.
+ (NSURL *)loginURLForClientId:(NSString *)clientId withRedirectURL:(NSURL *)redirectURL scopes:(NSArray *)scopes responseType:(NSString *)responseType
Parameters
- clientId
Your client ID as declared in the Spotify Developer Centre.
- redirectURL
Your callback URL as declared in the Spotify Developer Centre.
- scopes
The custom scopes to request from the auth API.
- responseType
Authentication response code type, defaults to “code”, use “token” if you want to bounce directly to the app without refresh tokens.
Return Value
The URL to pass to UIApplication
’s -openURL:
method.
Discussion
Warning: You must open this URL with the system handler to have the auth process happen in Safari. Displaying this inside your application is against the Spotify ToS.
Declared In
SPTAuth.h
loginURLForClientId:withRedirectURL:scopes:responseType:campaignId:
Returns a URL that, when opened, will begin the Spotify authentication process.
+ (NSURL *)loginURLForClientId:(NSString *)clientId withRedirectURL:(NSURL *)redirectURL scopes:(NSArray *)scopes responseType:(NSString *)responseType campaignId:(NSString *)campaignId
Parameters
- clientId
Your client ID as declared in the Spotify Developer Centre.
- redirectURL
Your callback URL as declared in the Spotify Developer Centre.
- scopes
The custom scopes to request from the auth API.
- responseType
Authentication response code type, defaults to “code”, use “token” if you want to bounce directly to the app without refresh tokens.
- campaignId
A Spotify-provided campaign token.
Return Value
The URL to pass to UIApplication
’s -openURL:
method.
Discussion
Warning: You must open this URL with the system handler to have the auth process happen in Safari. Displaying this inside your application is against the Spotify ToS.
Declared In
SPTAuth.h
Instance Methods
canHandleURL:
Find out if the given URL appears to be a Spotify authentication URL.
- (BOOL)canHandleURL:(NSURL *)callbackURL
Parameters
- callbackURL
The complete callback URL as triggered in your application.
Return Value
Returns YES
if the callback URL appears to be a Spotify auth callback, otherwise NO
.
Discussion
This method is useful if your application handles multiple URL types. You can pass every URL you receive through here to filter them.
Declared In
SPTAuth.h
handleAuthCallbackWithTriggeredAuthURL:callback:
Handle a Spotify authentication callback URL, returning a Spotify username and OAuth credential.
- (void)handleAuthCallbackWithTriggeredAuthURL:(NSURL *)url callback:(SPTAuthCallback)block
Parameters
- url
The complete callback URL as triggered in your application.
- block
The callback block to be triggered when authentication succeeds or fails.
Discussion
This URL is obtained when your application delegate’s application:openURL:sourceApplication:annotation:
method is triggered. Use [SPTAuth canHandleURL:]
to easily filter out other URLs that may be
triggered.
Declared In
SPTAuth.h
renewSession:callback:
Request a new access token using an existing SPTSession object containing a refresh token.
- (void)renewSession:(SPTSession *)session callback:(SPTAuthCallback)block
Parameters
- session
An SPTSession object with a valid refresh token.
- block
The callback block that will be invoked when the request has been performed.
Discussion
If no token refresh service has been specified the callback will return nil
as session.
Declared In
SPTAuth.h
spotifyAppAuthenticationURL
Returns a spotify-action:// URL that you can use to retrieve an access token
if [SPTAuth supportsApplicationAuthentication]
returns YES.
- (NSURL *)spotifyAppAuthenticationURL
Return Value
spotify-action:// URL for initiating a Spotfiy Client SSO attempt.
Discussion
Pass this URL to [UIApplication openURL:]
to launch the Spotify application on the device.
Note: This will authenticate and authorise for the user currently logged in to the Spotfiy application. There might be no option to switch user.
Declared In
SPTAuth.h
spotifyWebAuthenticationURL
Returns a https:// URL that you can use to retrieve an access token.
- (NSURL *)spotifyWebAuthenticationURL
Return Value
https:// URL for authenticating and authorising with the Spotify service
Discussion
Display this URL within a SFSafariViewController on iOS 9 and up, or UIWebView.
This is the preffered mode of authentication.
Note: This will always display an option to switch user.
Declared In
SPTAuth.h