BITAuthenticator Class Reference
Inherits from | BITHockeyBaseManager : NSObject |
Declared in | BITAuthenticator.h |
Overview
Identify and authenticate users of Ad-Hoc or Enterprise builds
BITAuthenticator
serves 2 purposes:
Identifying who is running your Ad-Hoc or Enterprise builds
BITAuthenticator
provides an identifier for the rest of the HockeySDK to work with, e.g. in-app update checks and crash reports.Optional regular checking if an identified user is still allowed to run this application. The
BITAuthenticator
can be used to make sure only users who are testers of your app are allowed to run it.
This module automatically disables itself when running in an App Store build by default!
Warning: It is mandatory to call authenticateInstallation
somewhen after calling
[[BITHockeyManager sharedHockeyManager] startManager]
or fully customize the identification
and validation workflow yourself.
If your app shows a modal view on startup, make sure to call authenticateInstallation
either once your modal view is fully presented (e.g. its viewDidLoad:
method is processed)
or once your modal view is dismissed.
Tasks
Configuration
-
identificationType
property -
restrictApplicationUsage
property -
restrictionEnforcementFrequency
property -
authenticationSecret
property -
delegate
property
Device based identification
-
webpageURL
property -
– deviceAuthenticationURL
-
urlScheme
property -
– handleOpenURL:sourceApplication:annotation:
Authentication
Properties
authenticationSecret
The authentication secret from HockeyApp. To find the right secret, click on your app on the HockeyApp dashboard, then on Show next to “Secret:”.
@property (nonatomic, copy) NSString *authenticationSecret
Discussion
This is only needed if identificationType
is set to BITAuthenticatorIdentificationTypeHockeyAppEmail
See Also
Declared In
BITAuthenticator.h
delegate
Delegate that can be used to do any last minute configurations on the presented viewController.
@property (nonatomic, weak) id<BITAuthenticatorDelegate> delegate
See Also
Declared In
BITAuthenticator.h
identificationType
Defines the identification mechanism to be used
@property (nonatomic, assign) BITAuthenticatorIdentificationType identificationType
Discussion
Default: BITAuthenticatorIdentificationTypeAnonymous
See Also
Declared In
BITAuthenticator.h
identified
Returns YES if this app is identified according to the setting in identificationType
.
@property (nonatomic, assign, readonly, getter=isIdentified) BOOL identified
Discussion
Since the identification process is done asynchronously (contacting the server), you need to observe the value change via KVO.
See Also
Declared In
BITAuthenticator.h
restrictApplicationUsage
Enables or disables checking if the user is allowed to run this app
@property (nonatomic, assign) BOOL restrictApplicationUsage
Discussion
If disabled, the Authenticator never validates, besides initial identification, if the user is allowed to run this application.
If enabled, the Authenticator checks depending on restrictionEnforcementFrequency
if the user is allowed to use this application.
Enabling this property and setting identificationType
to BITAuthenticatorIdentificationTypeHockeyAppEmail
,
BITAuthenticatorIdentificationTypeHockeyAppUser
or BITAuthenticatorIdentificationTypeWebAuth
also allows
to remove access for users by removing them from the app’s users list on HockeyApp.
Default: NO
Warning: if identificationType
is set to BITAuthenticatorIdentificationTypeAnonymous
,
this property has no effect.
Declared In
BITAuthenticator.h
restrictionEnforcementFrequency
Defines how often the BITAuthenticator checks if the user is allowed to run this application
@property (nonatomic, assign) BITAuthenticatorAppRestrictionEnforcementFrequency restrictionEnforcementFrequency
Discussion
This requires restrictApplicationUsage
to be enabled.
Default: BITAuthenticatorAppRestrictionEnforcementOnFirstLaunch
Declared In
BITAuthenticator.h
urlScheme
The url-scheme used to idenfify via BITAuthenticatorIdentificationTypeDevice
@property (nonatomic, strong) NSString *urlScheme
Discussion
Please make sure that the URL scheme is unique and not shared with other apps.
If set to nil, the default scheme is used which is ha<APP_ID>
.
Declared In
BITAuthenticator.h
validated
Indicates if this installation is validated.
@property (nonatomic, assign, readonly, getter=isValidated) BOOL validated
Declared In
BITAuthenticator.h
webpageURL
The baseURL of the webpage the user is redirected to if identificationType
is
set to BITAuthenticatorIdentificationTypeDevice
; defaults to https://rink.hockeyapp.net.
@property (nonatomic, strong) NSURL *webpageURL
See Also
Declared In
BITAuthenticator.h
Instance Methods
authenticateInstallation
Invoked automatic identification and validation
- (void)authenticateInstallation
Discussion
If the BITAuthenticator
is in automatic mode this will initiate identifying
the current user according to the type specified in identificationType
and
validate if the identified user is allowed to run this application.
If the user is not yet identified it will present a modal view asking the user to provide the required information.
If your app provides it’s own startup modal screen, e.g. a guide or a login, then you might either call this method once that UI is fully presented or once the user e.g. did actually login already.
Warning: You need to call this method in your code even if automatic mode is enabled!
See Also
Declared In
BITAuthenticator.h
cleanupInternalStorage
Removes all previously stored authentication tokens, UDIDs, etc.
- (void)cleanupInternalStorage
Declared In
BITAuthenticator.h
deviceAuthenticationURL
URL to query the device’s id via external webpage
Built with the baseURL set in webpageURL
.
- (NSURL *)deviceAuthenticationURL
Declared In
BITAuthenticator.h
handleOpenURL:sourceApplication:annotation:
Should be used by the appdelegate to forward handle application:openURL:sourceApplication:annotation: calls.
- (BOOL)handleOpenURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
Parameters
- url
Param
url
that was passed to the app
- sourceApplication
Param
sourceApplication
that was passed to the app
- annotation
Param
annotation
that was passed to the app
Return Value
YES if the URL request was handled, NO if the URL could not be handled/identified.
Discussion
This is required if identificationType
is set to BITAuthenticatorIdentificationTypeDevice
.
Your app needs to implement the default ha<APP_ID>
URL scheme or register its own scheme
via urlScheme
.
BITAuthenticator checks if the given URL is actually meant to be parsed by it and will
return NO if it doesn’t think so. It does this by checking the ‘host’-part of the URL to be ‘authorize’, as well
as checking the protocol part.
Please make sure that if you’re using a custom URL scheme, it does not conflict with BITAuthenticator’s.
If BITAuthenticator thinks the URL was meant to be an authorization URL, but could not find a valid token, it will
reset the stored identification token and state.
Sample usage (in AppDelegate):
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
if ([[BITHockeyManager sharedHockeyManager].authenticator handleOpenURL:url
sourceApplication:sourceApplication
annotation:annotation]) {
return YES;
} else {
//do your own URL handling, return appropriate value
}
return NO;
}
Declared In
BITAuthenticator.h
identifyWithCompletion:
Identifies the user according to the type specified in identificationType
.
- (void)identifyWithCompletion:(void ( ^ ) ( BOOL identified , NSError *error ))completion
Parameters
- completion
Block being executed once identification completed
Discussion
If the BITAuthenticator
is in manual mode, it’s your responsibility to call
this method. Depending on the identificationType
, this method
might present a viewController to let the user enter his/her credentials.
If the Authenticator is in auto-mode, this is called by the authenticator itself once needed.
Declared In
BITAuthenticator.h
publicInstallationIdentifier
Returns different values depending on identificationType
. This can be used
by the application to identify the user.
- (NSString *)publicInstallationIdentifier
See Also
Declared In
BITAuthenticator.h
validateWithCompletion:
Validates if the identified user is allowed to run this application. This checks with the HockeyApp backend and calls the completion-block once completed.
- (void)validateWithCompletion:(void ( ^ ) ( BOOL validated , NSError *error ))completion
Parameters
- completion
Block being executed once validation completed
Discussion
If the BITAuthenticator
is in manual mode, it’s your responsibility to call
this method. If the application is not yet identified, validation is not possible
and the completion-block is called with an error set.
If the BITAuthenticator
is in auto-mode, this is called by the authenticator itself
once needed.
Declared In
BITAuthenticator.h