Onboarding

The Snabble SDK contains functions to easily define the onboarding process of an app without having to program special views for this purpose. The structure of the onboarding is done via a JSON file.

The onboarding pages of the iOS Sample App:

Page 1	Page 2	Page 3

JSON Configuration

The description of the Onboarding is done via a JSON file. The file must contains two elements configuration and items.

{
    "configuration": {
        ...
    },
    "items": [
       ...
    ]
}

Configuration

The configuration element may contain a single imageSource element. The SDK uses the image specified there from the Asset catalog of the hosting app and displays it as the header image on each page of the onboarding.

Parameter	Type	Required	Example
imageSource	String?	no	"Onboarding/onboarding-logo"

Items

Every single page of the onboarding process is defined with an item element. The following keys are currently supported:

Parameter	Type	Required	Example
imageSource	String?	no	"Onboarding/onboarding-image-1"
text	String	yes	"Onboarding.message1"
link	String?	no	"imprint.html"
customButtonTitle	String?	no	"Onboarding.accept"

Parameter: imageSource

The imageSource parameter acts like the one in the configuration element. The SDK uses the image specified there from the Asset catalog of the hosting app and displays the image below the header image.

Parameter: text

Below the page image the localizable text is displayed.

text may contain markdown elements like:

"text": "Please accept the [terms](snabble://terms.html) of use."

or text may contain HTML tags like:

`"text": "Es gelten die <a href="snabble://terms.html">Nutzungsbedingungen</a>."

Parameter: link

The link parameter loads the given resource file from the apps resource bundle directory and display the content using a WebView. To trigger this action a button with the localizable key "Snabble.Onboarding.Link.show" is displayed below the text element.

Parameter: customButtonTitle

By default, a button with the localizable text "next" is displayed at the bottom of each page, navigating to the next onbaording page. On the last page, the localizable text "done" is displayed. The parameter customButtonTitle replaces the default button text.

Example

JSON Example of SnabbleSampleApp file Onboarding.json to show three onboarding pages as seen at the top of this document:

{
    "configuration" : {
        "imageSource" : "Onboarding/onboarding-logo"
    },
    "items" : [
        {
            "imageSource": "Onboarding/onboarding-image-1",
            "text": "Onboarding.message1",
        },
        {
            "imageSource": "Onboarding/onboarding-image-2",
            "text": "Onboarding.message2"
        },
        {
            "imageSource": "Onboarding/onboarding-image-3",
            "text": "Onboarding.message3",
            "link": "imprint.html",
            "customButtonTitle": "Onboarding.accept"
        }
    ]
}

Implementation

The sample app uses the following code fragment to display the Onboarding:

if Onboarding.isRequired {
    showOnboarding(on: tabBarController)
}

private func showOnboarding(on viewController: UIViewController) {
    let viewModel: OnboardingViewModel = loadJSON("Onboarding")
    let onboardingViewController = OnboardingViewController(viewModel: viewModel)
    onboardingViewController.delegate = self
    viewController.present(onboardingViewController, animated: false)
}

The function showOnboarding(on:) creates a view model using a helper function loadJSON(). This model is injected to the SDK OnboardingViewController.

To interact with the onboarding process the protocol:

/// Methods for managing completion of onboarding
public protocol OnboardingViewControllerDelegate: AnyObject {

    /// Tells the delegate that the onboarding is finished
    /// - Parameter viewController: A viewController informing the delegate about the completion
    func onboardingViewControllerDidFinish(_ viewController: OnboardingViewController)
}

is implemented by the Sample App delegate, which simply dismiss the onboarding view, when the last page button was pressed.

extension AppDelegate: OnboardingViewControllerDelegate {
    func onboardingViewControllerDidFinish(_ viewController: OnboardingViewController) {
        viewController.presentingViewController?.dismiss(animated: true)
    }
}