Spezi Onboarding

Provides UI components for Onboarding and Consent.

Overview

• The SpeziOnboarding module provides user interface components to onboard a user to an application;
• The SpeziConsent module provides utilities for retrieving consent for e.g. a study participation.

OnboardingView	SequentialOnboardingView	OnboardingConsentView

Setup

Add Spezi Onboarding as a Dependency

You need to add the Spezi Onboarding Swift package to your app in Xcode or Swift package.

Examples

Onboarding View

The OnboardingView allows you to separate information into areas on a screen, each with a title, description, and icon.

import SpeziOnboarding
import SwiftUI


struct OnboardingViewExample: View {
    var body: some View {
        OnboardingView(
            title: "Welcome",
            subtitle: "This is an example onboarding view",
            areas: [
                .init(
                    icon: Image(systemName: "tortoise.fill"), 
                    title: "Tortoise", 
                    description: "A Tortoise!"
                ),
                .init(
                    icon: {
                        Image(systemName: "lizard.fill")
                            .foregroundColor(.green)
                    },
                    title: "Lizard", 
                    description: "A Lizard!"
                ),
                .init(
                    icon: {
                        Circle().fill(.orange)
                    }, 
                    title: "Circle", 
                    description: "A Circle!"
                )
            ],
            actionText: "Learn More",
            action: {
                // Action to perform when the user taps the action button.
            }
        )
    }
}

Sequential Onboarding View

The SequentialOnboardingView allows you to display information step-by-step with each additional area appearing when the user taps the Continue button.

import SpeziOnboarding
import SwiftUI


struct SequentialOnboardingViewExample: View {
    var body: some View {
        SequentialOnboardingView(
            title: "Things to know",
            subtitle: "And you should pay close attention ...",
            content: [
                .init(
                    title: "A thing to know", 
                    description: "This is a first thing that you should know; read carefully!"
                ),
                .init(
                    title: "Second thing to know", 
                    description: "This is a second thing that you should know; read carefully!"
                ),
                .init(
                    title: "Third thing to know", 
                    description: "This is a third thing that you should know; read carefully!"
                )
            ],
            actionText: "Continue"
        ) {
            // Action to perform when the user has viewed all the steps
        }
    }
}

Onboarding Consent View

The OnboardingConsentView can be used to allow your users to read and agree to a document, e.g., a consent document for a research study or a terms and conditions document for an app. The document can be signed using a family and given name and a hand-drawn signature. The signed consent form can then be exported and shared as a PDF file.

The following example demonstrates how the OnboardingConsentView shown above is constructed by reading a consent form from a markdown file, creating a ConsentDocument and passing it to the OnboardingConsentView, and an action that should be performed once the consent has been given (which receives the exported consent form as a PDF), as well as a configuration defining the properties of the exported consent form.

The following example demonstrates using the OnboardingConsentView to present a consent form to the user as part of an onboarding flow. Once the consent if completed (i.e., the user signed it and filled out all required form elements), the user can continue to the next onboarding step. The view also uses the ConsentShareButton to allow the user to obtain a PDF-exported copy of their signed consent document.

import SpeziConsent
import SwiftUI

struct ConsentStep: View {
    let url: URL
    
    @State private var consentDocument: ConsentDocument?
    @State private var viewState: ViewState = .idle
    
    var body: some View {
        OnboardingConsentView(consentDocument: consentDocument) {
            // advance your Onboarding flow in response to the user having confirmed a completed consent document
        }
        .viewStateAlert(state: $viewState)
        .toolbar {
            ToolbarItem(placement: .primaryAction) {
                // give your user the ability to obtain a PDF version of the consent document they just signed
                ConsentShareButton(
                    consentDocument: consentDocument,
                    viewState: $viewState
                )
            }
        }
        .task {
            // load the consent document when the view is first displayed.
            // this will automatically cause the `OnboardingConsentView` above to update its contents.
            do {
                consentDocument = try ConsentDocument(contentsOf: url)
            } catch {
                viewState = .error(AnyLocalizedError(error: error))
            }
        }
    }
}

For more information, please refer to the API documentation.

The Spezi Template Application

The Spezi Template Application provides a great starting point and example using the SpeziOnboarding module.

Contributing

Contributions to this project are welcome. Please make sure to read the contribution guidelines and the contributor covenant code of conduct first.

License

This project is licensed under the MIT License. See Licenses for more information.