SBBAuthManagerProtocol Protocol Reference

Conforms to NSObject
Declared in SBBAuthManager.h

Overview

This protocol defines the interface to the SBBAuthManager’s non-constructor, non-initializer methods. The interface is abstracted out for use in mock objects for testing, and to allow selecting among multiple implementations at runtime.

– signUpStudyParticipant:completion: required method

Sign up for an account using a SignUp record, which is basically a StudyParticipant object with a password field. At minimum, at least one of the account identifying fields (email, phone, externalId) must be filled in; if the password field is not included, the only way to sign in will be via a link sent by email or via a token or link sent by SMS, so either email or phone would need to be filled in. In general, you would also want to fill in any of the following information available at sign-up time: firstName, lastName, sharingScope, dataGroups, notifyByEmail, and any custom attributes you’ve defined for the attributes field.

- (nullable NSURLSessionTask *)signUpStudyParticipant:(nonnull SBBSignUp *)signUp completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

signUp

A SBBSignUp object representing the participant signing up.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. Optional.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Declared In

SBBAuthManager.h

– signUpWithEmail:username:password:dataGroups:completion: required method

Sign up for an account with an email address, userName, password, and an optional list of data group tags. An email will be sent to the specified email address containing a link to verify that this is indeed that person’s email. The userName and password won’t be valid for signing in until the email has been verified. (Deprecated: Use signUpStudyParticipant:completion: instead.)

- (nullable NSURLSessionTask *)signUpWithEmail:(nonnull NSString *)email username:(nonnull NSString *)username password:(nonnull NSString *)password dataGroups:(nullable NSArray<NSString*> *)dataGroups completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

email

The email address to be associated with the account.

username

The username to use for the account.

password

The password to use for the account.

dataGroups

An array of dataGroup tags to assign to the user at signup. Optional.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. Optional.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Declared In

SBBAuthManager.h

– signUpWithEmail:username:password:completion: required method

Sign up for an account with an email address, userName, and password. This is a convenience method that calls signUpWithEmail:username:password:dataGroups:completion: with dataGroups set to nil. (Deprecated: Use signUpStudyParticipant:withPassword:completion: instead.)

- (nullable NSURLSessionTask *)signUpWithEmail:(nonnull NSString *)email username:(nonnull NSString *)username password:(nonnull NSString *)password completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

email

The email address to be associated with the account.

username

The username to use for the account.

password

The password to use for the account.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. Optional.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Declared In

SBBAuthManager.h

– resendEmailVerification:completion: required method

Request Bridge to re-send the email verification link to the specified email address.

- (nullable NSURLSessionTask *)resendEmailVerification:(nonnull NSString *)email completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

email

The email address for which to re-send the verification link.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Discussion

A 404 Not Found HTTP status indicates there is no pending verification for that email address, either because it was not used to sign up for an account, or because it has already been verified.

Declared In

SBBAuthManager.h

– resetUserSessionInfo required method

Reset UserSessionInfo and StudyParticipant to a pristine state and notify the auth delegate.

- (void)resetUserSessionInfo

Discussion

Note: This method should only be called if the prospective participant got partway through onboarding/consent, set some values on the StudyParticipant sub-object or its attributes, and decided to cancel or restart the whole process. It does nothing if we’re currently authenticated to Bridge (i.e. we have a session token). It also does nothing if there’s no auth delegate currently set, since no placeholder objects will have been created.

Declared In

SBBAuthManager.h

– signInWithCredential:value:password:completion: required method

Sign in to an existing account with an account-identifying credential (email, phone, or externalId) and password.

- (nullable NSURLSessionTask *)signInWithCredential:(nonnull NSString *)credentialKey value:(nonnull id<SBBJSONValue>)credentialValue password:(nonnull NSString *)password completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

credentialKey

The account-identifying credential (@"email", @"phone", or @"externalId") to use for signing in.

credentialValue

The value of the specified credential for the account being signed into. This is used by Bridge as a unique identifier for a participant within a study.

password

The password of the account.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. The responseObject will be an NSDictionary containing a Bridge API UserSessionInfo object in case you need to refer to it, but the SBBAuthManager handles the session token for all Bridge API access via this SDK, so you can generally ignore it if you prefer. If you’ve set up an auth delegate and implemented the authManager:didReceiveUserSessionInfo: method, the response object will also be converted to a SBBUserSessionInfo object and passed along to that method.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Declared In

SBBAuthManager.h

– signInWithEmail:password:completion: required method

Sign in to an existing account with an email and password.

- (nullable NSURLSessionTask *)signInWithEmail:(nonnull NSString *)email password:(nonnull NSString *)password completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

email

The email address of the account being signed into. This is used by Bridge as a unique identifier for a participant within a study.

password

The password of the account.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. The responseObject will be an NSDictionary containing a Bridge API UserSessionInfo object in case you need to refer to it, but the SBBAuthManager handles the session token for all Bridge API access via this SDK, so you can generally ignore it if you prefer. You can convert the responseObject to an SBBUserSessionInfo object (or whatever you’ve mapped it to) in your completion handler by calling [SBBComponent(SBBObjectManager) objectFromBridgeJSON:responseObject] (or substituting another instance of idSBBObjectManagerProtocol if you’ve set one up).

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Discussion

This is a convenience method that calls through to signInWithCredential:value:password:completion.

Declared In

SBBAuthManager.h

– signInWithPhone:password:completion: required method

Sign in to an existing account with an SBBPhone and password.

- (nullable NSURLSessionTask *)signInWithPhone:(nonnull SBBPhone *)phone password:(nonnull NSString *)password completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

phone

A SBBPhone object containing the phone number and region code for the account being signed into. This is used by Bridge as a unique identifier for a participant within a study.

password

The password of the account.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. The responseObject will be an NSDictionary containing a Bridge API UserSessionInfo object in case you need to refer to it, but the SBBAuthManager handles the session token for all Bridge API access via this SDK, so you can generally ignore it if you prefer. You can convert the responseObject to an SBBUserSessionInfo object (or whatever you’ve mapped it to) in your completion handler by calling [SBBComponent(SBBObjectManager) objectFromBridgeJSON:responseObject] (or substituting another instance of idSBBObjectManagerProtocol if you’ve set one up).

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Discussion

This is a convenience method that calls through to signInWithCredential:value:password:completion.

Declared In

SBBAuthManager.h

– signInWithPhoneNumber:regionCode:password:completion: required method

Sign in to an existing account with a phone number, region code, and password.

- (nullable NSURLSessionTask *)signInWithPhoneNumber:(nonnull NSString *)phoneNumber regionCode:(nonnull NSString *)regionCode password:(nonnull NSString *)password completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

phoneNumber

The phone number of the account being signed into (can be formatted in any way that’s useful for end users). This is used by Bridge as a unique identifier for a participant within a study.

regionCode

The CLDR two-letter region code describing the region in which the phone number was issued.

password

The password of the account.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. The responseObject will be an NSDictionary containing a Bridge API UserSessionInfo object in case you need to refer to it, but the SBBAuthManager handles the session token for all Bridge API access via this SDK, so you can generally ignore it if you prefer. You can convert the responseObject to an SBBUserSessionInfo object (or whatever you’ve mapped it to) in your completion handler by calling [SBBComponent(SBBObjectManager) objectFromBridgeJSON:responseObject] (or substituting another instance of idSBBObjectManagerProtocol if you’ve set one up).

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Discussion

This is a convenience method that calls through to signInWithCredential:value:password:completion.

Declared In

SBBAuthManager.h

– signInWithExternalId:password:completion: required method

Sign in to an existing account with an externalId and password.

- (nullable NSURLSessionTask *)signInWithExternalId:(nonnull NSString *)externalId password:(nonnull NSString *)password completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

externalId

The externalId of the account being signed into. This is used by Bridge as a unique identifier for a participant within a study.

password

The password of the account.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. The responseObject will be an NSDictionary containing a Bridge API UserSessionInfo object in case you need to refer to it, but the SBBAuthManager handles the session token for all Bridge API access via this SDK, so you can generally ignore it if you prefer. You can convert the responseObject to an SBBUserSessionInfo object (or whatever you’ve mapped it to) in your completion handler by calling [SBBComponent(SBBObjectManager) objectFromBridgeJSON:responseObject] (or substituting another instance of idSBBObjectManagerProtocol if you’ve set one up).

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Discussion

This is a convenience method that calls through to signInWithCredential:value:password:completion.

Declared In

SBBAuthManager.h

– reauthWithCompletion: required method

Reauthenticate the user to their Bridge using the reauthToken.

- (nullable NSURLSessionTask *)reauthWithCompletion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. Optional.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not been set up or if required reauth info is missing.

Declared In

SBBAuthManager.h

– emailSignInLinkTo:completion: required method

Send the user a link via email that they can use to sign in to their Bridge account.

- (nullable NSURLSessionTask *)emailSignInLinkTo:(nonnull NSString *)email completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

email

The email address to which to send the sign-in link. This must be the address associated with the user’s Bridge account.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. Optional.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if the study is not yet set up or the email parameter is an empty string. @seealso signInWithEmail:token:completion:

Discussion

The app will need to be set up to intercept the link and parse out the sign-in token, which it will then use to call signInWithEmail:token:completion: to complete the sign-in process.

Declared In

SBBAuthManager.h

– signInWithEmail:token:completion: required method

Sign in to an existing email-based account with the user’s email and a sign-in token parsed from a link received as a result of a call to emailSignInLinkTo:completion:.

- (nullable NSURLSessionTask *)signInWithEmail:(nonnull NSString *)email token:(nonnull NSString *)token completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

email

The email address of the account being signed into. This is used by Bridge as a unique identifier for a participant within a study.

token

The sign-in token as parsed from the link.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. Optional.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up. @seealso emailSignInLinkTo:completion:

Declared In

SBBAuthManager.h

– textSignInTokenTo:regionCode:completion: required method

Send the user a token (or a link containing a token) via SMS that they can use to sign in to their Bridge account.

- (nullable NSURLSessionTask *)textSignInTokenTo:(nonnull NSString *)phoneNumber regionCode:(nonnull NSString *)regionCode completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

phoneNumber

The phone number to which to send the sign-in token or link. This must be the number associated with the user’s Bridge account.

regionCode

The CLDR two-letter region code describing the region in which the phone number was issued.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. Optional.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if the study is not yet set up or either phoneNumber or regionCode is an empty string. @seealso signInWithPhone:regionCode:token:completion:

Discussion

If a link is sent, the app will need to be set up to intercept the link and parse out the sign-in token, which it will then use to call signInWithPhone:regionCode:token:completion: to complete the sign-in process.

If just a token is sent, the app will need to provide a UI for the user to manually enter the token (à la 2-factor authentication) and use that in the signIn call.

Declared In

SBBAuthManager.h

– signInWithPhoneNumber:regionCode:token:completion: required method

Sign in to an existing phone-based account with the user’s phone number and a sign-in token either received directly, or parsed from a link received, as a result of a call to textSignInLinkTo:regionCode:completion:.

- (nullable NSURLSessionTask *)signInWithPhoneNumber:(nonnull NSString *)phoneNumber regionCode:(nonnull NSString *)regionCode token:(nonnull NSString *)token completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

phoneNumber

The phone number of the account being signed into. This is used by Bridge as a unique identifier for a participant within a study.

regionCode

The CLDR two-letter region code describing the region in which the phone number was issued.

token

The sign-in token as received directly or as parsed from the link.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion. Optional.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up. @seealso textSignInLinkTo:regionCode:completion:

Declared In

SBBAuthManager.h

– signOutWithCompletion: required method

Sign out of the user’s Bridge account.

- (nullable NSURLSessionTask *)signOutWithCompletion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

completion

A SBBNetworkManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Declared In

SBBAuthManager.h

– ensureSignedInWithCompletion: required method

Call this at app launch to ensure the user is logged in to their account (if any).

- (void)ensureSignedInWithCompletion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

completion

A SBBNetworkManagerCompletionBlock to be called upon completion.

Discussion

The completion block should check for error code kSBBNoCredentialsAvailable and ask the user to sign up/sign in.

Declared In

SBBAuthManager.h

– requestPasswordResetForEmail:completion: required method

Request that the password be reset for the account associated with the given email address. An email will be sent to that address with instructions for choosing a new password.

- (nullable NSURLSessionTask *)requestPasswordResetForEmail:(nonnull NSString *)email completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

email

The email address associated with the account whose password is to be reset.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Declared In

SBBAuthManager.h

– resetPasswordToNewPassword:resetToken:completion: required method

Reset the password for this user’s account.

- (nullable NSURLSessionTask *)resetPasswordToNewPassword:(nonnull NSString *)password resetToken:(nonnull NSString *)token completion:(nullable SBBNetworkManagerCompletionBlock)completion

Parameters

password

The new password for this user’s account.

token

The sptoken sent to the user’s email address in response to a requestPasswordResetForEmail: call.

completion

A SBBNetworkManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request, or nil if BridgeSDK has not yet been set up.

Declared In

SBBAuthManager.h

– addAuthHeaderToHeaders: required method

This method is used by other API manager components to inject the session token header for authentication.

- (void)addAuthHeaderToHeaders:(nonnull NSMutableDictionary *)headers

Parameters

headers

A mutable dictionary containing HTTP header key-value (string) pairs, to which to add the auth header.

Declared In

SBBAuthManager.h

– isAuthenticated required method

This method is used by the Participant Manager to determine whether to propagate StudyParticipant changes to cache and to Bridge. Until the participant has successfully signed up and signed in, a placeholder StudyParticipant exists for convenience, and will be used to help populate the signUp request JSON.

- (BOOL)isAuthenticated

Return Value

Whether the auth manager is currently authenticated (has a session token which may or may not be currently valid)

Declared In

SBBAuthManager.h

– signInWithUsername:password:completion:

For backward compatibility only. Use signInWithEmail:password:completion instead (which this method now calls).

- (nullable NSURLSessionTask *)signInWithUsername:(nonnull NSString *)username password:(nonnull NSString *)password completion:(nullable SBBNetworkManagerCompletionBlock)completion

Declared In

SBBAuthManager.h