SBBParticipantManager Class Reference

Inherits from SBBBridgeAPIManager : NSObject
Conforms to SBBComponent
SBBParticipantManagerProtocol
Declared in SBBParticipantManager.h
SBBParticipantManager.m

Overview

This class handles communication with the Bridge Participants API, and with the client-facing participant reports endpoints (which for historical reasons still use the otherwise mostly-deprecated Users API).

Other Methods

+ dataSharingScopeStrings

Returns an array for mapping SBBParticipantDataSharingScope enum values to their Bridge string equivalents.

+ (nonnull NSArray<NSString*> *)dataSharingScopeStrings

Declared In

SBBParticipantManager.h

Other Methods

– getParticipantRecordWithCompletion:

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

- (NSURLSessionTask *)getParticipantRecordWithCompletion:(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:

Update the StudyParticipant record to the Bridge API.

- (NSURLSessionTask *)updateParticipantRecordWithRecord:(id)participant completion:(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:

Add an external identifier for a participant.

- (NSURLSessionTask *)setExternalIdentifier:(NSString *)externalID completion:(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:

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.

- (NSURLSessionTask *)setSharingScope:(SBBParticipantDataSharingScope)scope completion:(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:

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.

- (NSURLSessionTask *)getDataGroupsWithCompletion:(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:

Update the participant’s dataGroups to the Bridge API.

- (NSURLSessionTask *)updateDataGroupsWithGroups:(NSSet<NSString*> *)dataGroups completion:(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:

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

- (NSURLSessionTask *)addToDataGroups:(NSSet<NSString*> *)dataGroups completion:(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:

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

- (NSURLSessionTask *)removeFromDataGroups:(NSSet<NSString*> *)dataGroups completion:(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:fromDate:toDate:completion:

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

- (NSURLSessionTask *)getReport:(NSString *)identifier fromDate:(NSDateComponents *)fromDate toDate:(NSDateComponents *)toDate completion:(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

– getReport:fromTimestamp:toTimestamp:completion:

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

- (NSURLSessionTask *)getReport:(NSString *)identifier fromTimestamp:(NSDate *)fromTimestamp toTimestamp:(NSDate *)toTimestamp completion:(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

– saveReportData:forReport:completion:

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

- (NSURLSessionTask *)saveReportData:(SBBReportData *)reportData forReport:(NSString *)identifier completion:(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:

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

- (NSURLSessionTask *)saveReportJSON:(id)reportJSON withDateTime:(NSDate *)dateTime forReport:(NSString *)identifier completion:(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:

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.

- (NSURLSessionTask *)saveReportJSON:(id)reportJSON withLocalDate:(NSDateComponents *)dateComponents forReport:(NSString *)identifier completion:(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:

Get the latest cached report data from the given report.

- (SBBReportData *)getLatestCachedDataForReport:(NSString *)identifier error:(NSError **)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