SBBParticipantManagerProtocol Protocol Reference

Conforms to SBBBridgeAPIManagerProtocol
Declared in SBBParticipantManager.h

Overview

This protocol defines the interface to the SBBParticipantManager’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.

– getParticipantRecordWithCompletion: required method

Fetch the StudyParticipant record from cache if caching is turned on, otherwise from the Bridge API.

- (nullable NSURLSessionTask *)getParticipantRecordWithCompletion:(nullable SBBParticipantManagerGetRecordCompletionBlock)completion

Parameters

completion

An SBBParticipantManagerGetRecordCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Discussion

Note that if BridgeSDK was initialized with caching, the StudyParticipant record will always exist in the cache once the client has signed in for the first time, and since StudyParticipant is client-updatable, the cached copy would take priority over whatever Bridge responded with, so with caching turned on, this method will never try to retrieve the StudyParticipant from Bridge.

Note also that the UserSessionInfo object received from Bridge on signIn is a superset of StudyParticipant, and upon successful signIn, any existing StudyParticipant object is deleted from cache and re-created from the UserSessionInfo. If any changes are made to the StudyParticipant on the Bridge server that didn’t come from this client, the client’s sessionToken should be invalidated, forcing the client to sign back in and thus update its cached StudyParticipant from the server.

Declared In

SBBParticipantManager.h

– updateParticipantRecordWithRecord:completion: required method

Update the StudyParticipant record to the Bridge API.

- (nullable NSURLSessionTask *)updateParticipantRecordWithRecord:(nullable id)participant completion:(nullable SBBParticipantManagerCompletionBlock)completion

Parameters

participant

A client object representing the StudyParticipant record as it should be updated. If caching is enabled and you want to sync changes you’ve made to the local (cached) SBBStudyParticipant to Bridge, pass nil for this parameter.

completion

An SBBParticipantManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Declared In

SBBParticipantManager.h

– setExternalIdentifier:completion: required method

Add an external identifier for a participant.

- (nullable NSURLSessionTask *)setExternalIdentifier:(nullable NSString *)externalID completion:(nullable SBBParticipantManagerCompletionBlock)completion

Parameters

externalID

An external identifier to allow this participant to be tracked outside of the Bridge-specific study.

completion

An SBBParticipantManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Discussion

This is a convenience method that sets the participant record’s externalId field and updates it to Bridge.

Note: Mainly intended as a quick replacement for the deprecated SBBUserManager addExternalIdentifier:completion: method. Generally you would have the participant enter their externalId during the onboarding process and include it when calling SBBAuthManager signUpStudyParticipant:withPassword:completion:.

Declared In

SBBParticipantManager.h

– setSharingScope:completion: required method

Change the scope of data sharing for this participant. This is a convenience method that sets the participant record’s sharingScope field and updates it to Bridge. This should only be done in response to an explicit choice on the part of the user to change the sharing scope.

- (nullable NSURLSessionTask *)setSharingScope:(SBBParticipantDataSharingScope)scope completion:(nullable SBBParticipantManagerCompletionBlock)completion

Parameters

scope

The scope of data sharing to set for this participant.

completion

An SBBParticipantManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Discussion

Note: Replaces deprecated SBBUserManager dataSharing:completion: method.

Declared In

SBBParticipantManager.h

– getDataGroupsWithCompletion: required method

Fetch the data groups to which this participant belongs from the Bridge API. This is a convenience method which fetches the StudyParticipant record (from cache, if available, otherwise from Bridge) and passes its dataGroups to the completion handler.

- (nullable NSURLSessionTask *)getDataGroupsWithCompletion:(nonnull SBBParticipantManagerGetGroupsCompletionBlock)completion

Parameters

completion

An SBBParticipantManagerGetGroupsCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Declared In

SBBParticipantManager.h

– updateDataGroupsWithGroups:completion: required method

Update the participant’s dataGroups to the Bridge API.

- (nullable NSURLSessionTask *)updateDataGroupsWithGroups:(nonnull NSSet<NSString*> *)dataGroups completion:(nullable SBBParticipantManagerCompletionBlock)completion

Parameters

dataGroups

An NSSet of strings representing the dataGroups as they should be updated.

completion

An SBBParticipantManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Discussion

This method writes a StudyParticipant record consisting of just the dataGroups field to the Bridge server. You may set the dataGroups directly as part of the StudyParticipant record when signing up for a Bridge account, but afterward should always update them via this method or one of the convenience methods that calls it

Note: If using caching, be aware that calling this method (or any of the convenience methods which call it) will remove unexpired, unfinished scheduled activities from the cache. The next call to get scheduled activities will replace them with the correct schedule going forward for the new set of data groups. If you’re not using the SDK’s built-in caching, you will need to take care of this yourself.

Declared In

SBBParticipantManager.h

– addToDataGroups:completion: required method

Add the participant to the specified data groups (tags).

- (nullable NSURLSessionTask *)addToDataGroups:(nonnull NSSet<NSString*> *)dataGroups completion:(nullable SBBParticipantManagerCompletionBlock)completion

Parameters

dataGroups

The data groups to which to add the participant. This is a convenience method which first calls getDataGroupsWithCompletion:, and in its completion handler, adds the specified groups to the returned dataGroups and posts the modified dataGroups back to the Bridge API via updateDataGroupWithGroups:completion:. If there is an error fetching the participant’s existing dataGroups, that error will be passed to the completion handler. If an attempt is made to add a participant to one or more data groups that haven’t first been defined in the study, the Bridge API will respond with 400 (Bad Request) with an error message detailing the problem in the body of the response.

completion

An SBBParticipantManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Declared In

SBBParticipantManager.h

– removeFromDataGroups:completion: required method

Remove the participant from the specified data groups (tags).

- (nullable NSURLSessionTask *)removeFromDataGroups:(nonnull NSSet<NSString*> *)dataGroups completion:(nullable SBBParticipantManagerCompletionBlock)completion

Parameters

dataGroups

The data groups from which to remove the participant. This is a convenience method which first calls getDataGroupsWithCompletion:, and in its completion handler, removes the specified groups from the returned dataGroups and posts the modified dataGroups back to the Bridge API via updateDataGroupWithGroups:completion:. If there is an error fetching the participant’s existing dataGroups, that error will be passed to the completion handler. If the fetch succeeds but the participant is not a member of one or more of these data groups, whether because they haven’t been added or because they don’t exist in the study, this method will complete without updating the participant’s dataGroups and without an error.

completion

An SBBParticipantManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Declared In

SBBParticipantManager.h

– getReport:fromTimestamp:toTimestamp:completion: required method

Get the specified report data items for the user over the given time span.

- (nullable NSURLSessionTask *)getReport:(nonnull NSString *)identifier fromTimestamp:(nonnull NSDate *)fromTimestamp toTimestamp:(nonnull NSDate *)toTimestamp completion:(nonnull SBBParticipantManagerGetReportCompletionBlock)completion

Parameters

identifier

The report identifier.

fromTimestamp

The start of the desired date range.

toTimestamp

The end of the desired date range.

completion

An SBBParticipantManagerGetReportCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Discussion

With this version of the method, you specify the desired time range with NSDate objects and they are interpreted as millisecond timestamps marking the starting and ending points of the desired span. You should use this method for retrieving ReportData objects from reports that use dateTime timestamps.

Declared In

SBBParticipantManager.h

– getReport:fromDate:toDate:completion: required method

Get the specified report data items for the user over the given date range.

- (nullable NSURLSessionTask *)getReport:(nonnull NSString *)identifier fromDate:(nonnull NSDateComponents *)fromDate toDate:(nonnull NSDateComponents *)toDate completion:(nonnull SBBParticipantManagerGetReportCompletionBlock)completion

Parameters

identifier

The report identifier.

fromDate

The first date to fetch.

toDate

The last date to fetch.

completion

An SBBParticipantManagerGetReportCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Discussion

With this version of the method, you specify the desired date range with NSDateComponents objects and they are interpreted as calendar dates marking the first and last dates (inclusive) for which ReportData objects are being requested. You should use this method for retrieving ReportData objects from reports that use localDate datestamps.

Declared In

SBBParticipantManager.h

– saveReportData:forReport:completion: required method

Save the specified ReportData object to the given report identifier. Any existing ReportData for the specified report with the same date

- (nullable NSURLSessionTask *)saveReportData:(nonnull SBBReportData *)reportData forReport:(nonnull NSString *)identifier completion:(nullable SBBParticipantManagerCompletionBlock)completion

Parameters

reportData

An SBBReportData object to be saved.

identifier

The identifier of the report to which this reportData is to be saved.

completion

An SBBParticipantManagerCompletionBlock to be called upon completion.

Return Value

An NSURLSessionTask object so you can cancel or suspend/resume the request.

Discussion

Note: A ReportData Bridge object can have either a full ISO8601 timestamp, represented by the dateTime field, or a date-only “datestamp”, represented by the localDate field. The date field of SBBReportData is an NSDate object, which represents the same time as, and serializes to/from JSON by copying, whichever of dateTime or localDate is set. To use the localDate (date-only) datestamp, use setDateComponents: and make sure the hour component of the date components is NSDateComponentUndefined (or nil in Swift). To use the dateTime timestamp, you can either set the date property with an NSDate (Date), or use the date components setter with a defined value for the hours component. Whichever you use, all ReportData records saved to a given report identifier should use the same one.

Declared In

SBBParticipantManager.h

– saveReportJSON:withDateTime:forReport:completion: required method

Save the specified report JSON data to the given report identifier with the specified dateTime timestamp.

- (nullable NSURLSessionTask *)saveReportJSON:(nonnull id<SBBJSONValue>)reportJSON withDateTime:(nonnull NSDate *)dateTime forReport:(nonnull NSString *)identifier completion:(nullable SBBParticipantManagerCompletionBlock)completion

Discussion

This is a convenience method that builds an SBBReportData object and calls through to saveReportData:forReport:completion:.

Declared In

SBBParticipantManager.h

– saveReportJSON:withLocalDate:forReport:completion: required method

Save the specified report JSON data to the given report identifier with the specified localDate (date-only) datestamp. Any date components smaller than a day (hour, minute, etc.) will be ignored.

- (nullable NSURLSessionTask *)saveReportJSON:(nonnull id<SBBJSONValue>)reportJSON withLocalDate:(nonnull NSDateComponents *)dateComponents forReport:(nonnull NSString *)identifier completion:(nullable SBBParticipantManagerCompletionBlock)completion

Discussion

This is a convenience method that builds an SBBReportData object and calls through to saveReportData:forReport:completion:.

Declared In

SBBParticipantManager.h

– getLatestCachedDataForReport:error: required method

Get the latest cached report data from the given report.

- (nullable SBBReportData *)getLatestCachedDataForReport:(nonnull NSString *)identifier error:(NSError *_Nullable *_Nullable)error

Parameters

identifier

The identifier for the report to be searched.

error

A pointer to an NSError reference, which this method will fill in if there’s an error processing the fetch request. Optional (as always).

Return Value

The SBBReportData object from the given report identifier with the most recent date.

Declared In

SBBParticipantManager.h