AIMobileLib
IntroductionAIMobileLib is a static class that contains Login with Amazon APIs. This class provides APIs for getting authorization from users, getting profile information, clearing authorization state, and getting authorization tokens to access secure data. Methods
authorizeUserForScopes:delegate:Allows the user to login and, if necessary, authorize the application for the requested scopes. + (void) authorizeUserForScopes:(NSArray*)scopes delegate:(id<AIAuthenticationDelegate>)authenticationDelegate; Parameters
Return ValuePass in a valid instance of AIAuthenticationDelegate to receive success and failure notifications. If authorization succeeds the requestDidSucceed: method is called on the delegate. The application can now call getProfile: to retrieve the user's profile data, or getAccessTokenForScopes:withOverrideParams:delegate: to retrieve the raw access token. If authorization fails the requestDidFail: method is called on the delegate. The error code and an error message are passed to the method in an APIError object. authorizeUserForScopes can produce the following error codes: 1. kAIUnauthorizedClient - The application is not authorized to make this call. 2. kAIInternalError - An internal error occured in the SDK. You can allow the user to login again. 3. kAIErrorUserInterrupted - The user canceled the login page. You can allow the user to login again. 4. kAIInvalidInput - One of the API parameters is invalid. See the error message for more information. 5. kAIDeviceError - The SDK encountered an error on the device. Currently, the SDK only throws this error when it receives the same error from the keychain service. Calling clearAuthorizationState: will help. 6. kAINetworkError - A network error occurred, possibly due to the user being offline. 7. kAIServerError - The server encountered an error while completing the request, or the SDK received an unknown response from the server. You can allow the user to login again. 8. kAIAccessDenied - The user did not consent to the requested scopes. DiscussionUse this method to request authorization from the user for the required scopes. If the user has not logged in, they will see a login page. Afterward, if they have not previously approved these scopes for your application, they will see a consent page. The sign in page is displayed in the Safari web browser, so there will be a visible switch from the application to the Safari browser. After the user signs in on the browser, they are redirected back to the app. The application must define the application:openURL:sourceApplication:annotation application delegate and call the handleOpenURL:sourceApplication: API from that delegate. This allows the SDK to get the login information from the Safari web browser. Scopes that can be used with this API are:
clearAuthorizationState:Deletes cached user tokens and other data. Use this method to logout a user. + (void)clearAuthorizationState:(id<AIAuthenticationDelegate>)authenticationDelegate; Parameters
Return ValuePass in a valid instance of AIAuthenticationDelegate to receive success and failure notifications. If clearing succeeds the requestDidSucceed: method is called on the delegate. If clearing fails the requestDidFail: method is called on the delegate. The error code and an error message are passed to the method in an APIError object. clearAuthorizationState can produce the following error codes: 1. kAIInvalidInput - One of the API parameters is invalid. See the error message for more information. 2. kAIDeviceError - The SDK encountered an error on the device. Currently, the SDK only throws this error when it receives the same error from the keychain service. Calling clearAuthorizationState: will help. DiscussionThis method removes the authorization tokens from the key chain. It also clears the cookies from the local cookie storage to clear the authorization state of the users who checked the "Remember me" checkbox.
getAccessTokenForScopes:withOverrideParams:delegate:Once the user has logged in, this method will return a valid access token for the requested scopes. + (void) getAccessTokenForScopes:(NSArray*)scopes withOverrideParams:(NSDictionary*)overrideParams delegate:(id<AIAuthenticationDelegate>)authenticationDelegate; Parameters
Return ValuePass in a valid instance of AIAuthenticationDelegate to receive success and failure notifications. If authorization succeeds the requestDidSucceed: method is called on the delegate. The new access token is passed in the result property of the APIResult parameter. The application can then use the access token directly with services that support it. If authorization fails the requestDidFail: method is called on the delegate. The error code and an error message are passed to the method in an APIError object. getAccessTokenForScopes can produce the following error codes: 1. kAIApplicationNotAuthorized - The application is not authorized for scopes requested. Call authorizeUserForScopes to allow the user to authorize the application. 2. kAIUnauthorizedClient - The application is not authorized to make this call. 3. kAIInternalError - An internal error occured in the SDK. You can retry the method call. 4. kAIInvalidInput - One of the API parameters is invalid. See the error message for more information. 5. kAIDeviceError - The SDK encountered an error on the device. Currently, the SDK only throws this error when it receives the same error from the keychain service. Calling clearAuthorizationState: will help. 6. kAINetworkError - A network error occurred, possibly due to the user being offline. 7. kAIServerError - The server encountered an error while completing the request, or the SDK received an unknown response from the server. You can retry the method call. DiscussionThis method returns a valid access token, if necessary by exchanging the current refresh token for a new access token. If the method is successful, this access token is valid for the requested scopes. If the API is called with the kForceRefresh override property set to "YES", the SDK discards the existing access token and requests a new access token.
getProfile:Use this method to get the profile of the current authorized user. + (void) getProfile:(id<AIAuthenticationDelegate>)authenticationDelegate; Parameters
Return ValuePass in a valid instance of AIAuthenticationDelegate to receive success and failure notifications. If the profile is retrieved successfully the requestDidSucceed: method is called on the delegate. The user profile is passed in the result property of the APIResult parameter as a dictionary. That dictionary includes key:value pairs with the following keys: 1. "name" - The name of the user. 2. "email" - The registered email address of the user. 3. "user_id" - The used id of the user, in the form of "amzn1.user.VALUE". The user id is unique to the user. 4. "postal_code" - The registered postal code of the user. If authorization fails the requestDidFail: method is called on the delegate. The error code and an error message are passed to the method in an APIError object. getAccessTokenForScopes can produce the following error codes: 1. kAIApplicationNotAuthorized - The application is not authorized for the "profile" scope. Call authorizeUserForScopes:delegate: to prompt the user to login and authorize the application. 2. kAIInternalError - An internal error occured in the SDK. You can retry the method call. 3. kAIInvalidInput - One of the API parameters is invalid. See the error message for more information. 4. kAIDeviceError - The SDK encountered an error on the device. Currently, the SDK only throws this error when it receives the same error from the keychain service. Calling clearAuthorizationState: will help. 5. kAINetworkError - A network error occurred, possibly due to the user being offline. 6. kAIServerError - The server encountered an error while completing the request, or the SDK received an unknown response from the server. You can retry the method call. DiscussionThis method gets profile information for the current authorized user. The application should make sure it is authorized for the "profile" scope prior to calling this method. If the application is authorized for the "postal_code" scope, getProfile will return that information as well. This profile information is cached for 60 minutes.
handleOpenURL:sourceApplication:Helper function for authorizeUserForScopes:delegate:. Call this function from your implementation of application:openURL:sourceApplication:annotation delegate. + (BOOL) handleOpenURL:(NSURL*)url sourceApplication:(NSString*)sourceApplication; ParametersReturn ValueReturns YES if the url passed in was a valid url from SDK's reference and NO if the url was not valid. DiscussionThis method handles the application:openURL:sourceApplication:annotation call from the Safari web browser. The application should be calling this function when it receives a call to application:openURL:sourceApplication:annotation, passing in the url and the sourceApplication. If application fails to do so, the SDK will not be able to complete the login flow. The SDK validates the url parameter to check if the url is valid for the SDK. It is possible the application may want to handle the url as well, in which case the application should first call the SDK to see if this url is a callback from safari and if the SDK wants to process it. After processing, the SDK will return its preference and the application can then process the url if it chooses. Any error arising from this API is reported through the failure delegate used for the authorizeUserForScopes:delegate: call. See authorizeUserForScopes:delegate: for more discussion on how to work with this API to complement the login work flow.
Constants
kForceRefreshKey name for defining whether to force a refresh of the access token. extern const NSString* kForceRefresh; DiscussionPass this key with a string value of "YES" to getAccessTokenForScopes:withOverrideParams:delegate: to force the method to refresh the access token.
|