Inherits from BITHockeyBaseManager : NSObject
Declared in BITAuthenticator.h

Overview

Identify and authenticate users of Ad-Hoc or Enterprise builds

BITAuthenticator serves 2 purposes:

  1. 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.

  2. 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.

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

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

Declared In

BITAuthenticator.h

identificationType

Defines the identification mechanism to be used

@property (nonatomic, assign) BITAuthenticatorIdentificationType identificationType

Discussion

Default: BITAuthenticatorIdentificationTypeAnonymous

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.

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

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!

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

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