SDK Reference v2.0.0 / ParticipantSession
ParticipantSession
final class ParticipantSession
Provides a context for performing authenticated actions on behalf of the participant.
An instance of ParticipantSession should be retained for the lifetime of a participant’s access token. Callers are responsible for tracking the state of an access token and renewing as needed.
Requests to the MyDataHelps platform are typically asynchronous. All asynchronous requests in ParticipantSession are implemented as Swift async functions. Async functions in ParticipantSession will throw errors for any failures in communicating with the MyDataHelps platform. All thrown errors are of type MyDataHelpsError.
Read the Programming Guide to understand general concepts and best practices for working with ParticipantSession and MyDataHelpsKit.
init(client: accessToken:)
init(client: MyDataHelpsClient, accessToken: ParticipantAccessToken)
Initializes a new session using an access token.
client
The client to use for all API access by this session.
accessToken
An authentication token. Must be valid and not expired, or all actions performed with this session will fail with authorization failures.
getParticipantInfo()
func getParticipantInfo() async throws -> ParticipantInfo
Retrieves basic information about the participant.
- Returns: An asynchronously-delivered
ParticipantInfo instance, if successful. Throws a MyDataHelpsError if unsuccessful.
getProjectInfo()
func getProjectInfo() async throws -> ProjectInfo
Retrieves general project information.
- Returns: An asynchronously-delivered
ProjectInfo instance, if successful. Throws a MyDataHelpsError if unsuccessful.
getDataCollectionSettings()
func getDataCollectionSettings() async throws -> ProjectDataCollectionSettings
Retrieves settings related to data collection for the participant and their project.
- Returns: An asynchronously-delivered
ProjectDataCollectionSettings instance, if successful. Throws a MyDataHelpsError if unsuccessful.
queryDeviceData(_:)
func queryDeviceData(_ query: DeviceDataQuery) async throws -> DeviceDataResultPage
Queries device data for the participant.
To fetch the first page of results, call this with a new DeviceDataQuery object. If there are additional pages available, the next page can be fetched by using DeviceDataQuery.page(after:) to construct a query for the following page.
query
Specifies how to filter the data, and optionally which page of data to fetch.
persistDeviceData(_:)
func persistDeviceData(_ dataPoints: [DeviceDataPointPersistModel]) async throws
Creates new and/or updates existing device data points. Each device data point is uniquely identified by a combination of its properties, called a natural key, as identified in DeviceDataPointPersistModel. Data points are always persisted with the project namespace.
To update an existing device data point, persist one whose natural key properties exactly match the one to be updated. All non-natural key properties will be updated to your persisted point.
To add a new device data point, provide enough natural key properties to uniquely identify it. Recommended properties include identifier, type and observationDate; these can be made into a unique combination for most device data points.
dataPoints
A set of data points to persist.
querySurveyTasks(_:)
func querySurveyTasks(_ query: SurveyTaskQuery) async throws -> SurveyTaskResultPage
Query a list of tasks, often used to display a list of certain tasks to a participant.
To fetch the first page of results, call this with a new SurveyTaskQuery object. If there are additional pages available, the next page can be fetched by using SurveyTaskQuery.page(after:) to construct a query for the following page.
query
Specifies how to filter the data, and optionally which page of data to fetch.
querySurveyAnswers(_:)
func querySurveyAnswers(_ query: SurveyAnswersQuery) async throws -> SurveyAnswersPage
Retrieve past survey answers from QuestionSteps, FormSteps, or WebViewSteps. Often this is used to display past answers to the participant.
To fetch the first page of results, call this with a new SurveyAnswersQuery object. If there are additional pages available, the next page can be fetched by using SurveyAnswersQuery.page(after:) to construct a query for the following page.
query
Specifies how to filter the data, and optionally which page of data to fetch.
deleteSurveyResult(_:)
func deleteSurveyResult(_ surveyResultID: SurveyResult.ID) async throws
Deletes a survey result for a participant. This feature is only available for surveys with “Results Can Be Deleted” enabled. This option can be enabled from the survey editor Settings pane in MyDataHelps Designer.
This operation CANNOT be undone.
surveyResultID
Auto-generated, globally-unique identifier for the survey submission to delete.
queryNotifications(_:)
func queryNotifications(_ query: NotificationHistoryQuery) async throws -> NotificationHistoryPage
Queries the history of notifications sent to this participant.
To fetch the first page of results, call this with a new NotificationHistoryQuery object. If there are additional pages available, the next page can be fetched by using NotificationHistoryQuery.page(after:) to construct a query for the following page.
query
Specifies how to filter the data, and optionally which page of data to fetch.
surveyPresentation(surveyName:)
func surveyPresentation(surveyName: String) -> SurveyPresentation
Prepares a model object used for presenting a SurveyViewController. See SurveyViewController documentation for more information.
surveyName
The name of the survey to present. In MyDataHelps Designer, this survey must be published to the project the participant is interacting with.
queryExternalAccountProviders(_:)
func queryExternalAccountProviders(_ query: ExternalAccountProvidersQuery) async throws -> ExternalAccountProvidersResultPage
Query the list of external account providers supported by MyDataHelps.
To fetch the first page of results, call this with a new ExternalAccountProvidersQuery object. If there are additional pages available, the next page can be fetched by using ExternalAccountProvidersQuery.page(after:) to construct a query for the following page.
query
Specifies how to filter the providers.
connectExternalAccount(providerID: finalRedirectURL:)
func connectExternalAccount(providerID: ExternalAccountProvider.ID, finalRedirectURL: URL) async throws -> ExternalAccountAuthorization
Initiates a new connected external account. Grants access to a secure OAuth connection to the specified external account provider, where the participant can provide their provider credentials and authorize MyDataHelps to retrieve data from the account.
After receiving the ExternalAccountAuthorization returned by this function, your app must present an SFSafariViewController to the user using the authorizationURL in the returned object to complete the provider authorization flow.
See External Account Connections for a detailed guide to implementing this feature in your app.
providerID
The ID of the external account provider to connect.
finalRedirectURL
A URL that is configured to open your app via a custom scheme or Universal Link.
listExternalAccounts()
func listExternalAccounts() async throws -> [ExternalAccount]
Fetches a list of all of the participant’s connected external accounts.
- Returns: An asynchronously-delivered list of connected counts, if successful. Throws a
MyDataHelpsError if unsuccessful.
refreshExternalAccount(_:)
func refreshExternalAccount(_ id: ExternalAccount.ID) async throws
Requests the refresh of data from a connected external account.
This API only begins the process of refreshing an account; the process may take additional time to complete. To track the status of a refresh, use ParticipantSession.listExternalAccounts to poll the status value of an account, checking for fetchingData or fetchComplete status values.
id
The ID of the external account to refresh.
deleteExternalAccount(_:)
func deleteExternalAccount(_ id: ExternalAccount.ID) async throws
Deletes an external account.
This API is idempotent: the result will indicate success even if the account was already disconnected, or the participant had no such account.
account
The ID of the external account to disconnect.