QR code for onboarding iOS app with Fiori Flows

Onboarding a new user to an iOS app which connects to backend data & authenticates via SAP Cloud Platform Mobile Services always involves telling the app which Mobile Services tenant to connect to, and typically how to try to authenticate.  Two of the most common techniques for this are to a) hardcode the connection settings in a plist, and b) use SAP’s Discovery Service, which takes a user’s email address, and does a central lookup to see if connection settings are available for that user’s domain.

These techniques show up by default in apps generated by the SAP Cloud Platform SDK for iOS Assistant, and are recommended for most cases.

There are however other supported techniques, including encoding the connection settings in a QR code image, and using device management channels.  One of our SAP app teams is looking at the QR code option, so I wanted to share a very short how-to.

Getting the QR Code

The correct QR code for an application’s Mobile Services configuration is always available in the Mobile Services Cockpit, on the Application Details page, under the “API’s” tab.

Save the QR code as a PNG file, and set it aside to use in a moment.

Configure Fiori Flows for QR Scanner

Note:  If you do not yet have an Assistant-generated Xcode project, please complete this tutorial:  Create an App Using the SAP Cloud Platform SDK for iOS Assistant, to ensure you have the relevant code snippets to modify for this use case.

The WelcomeScreenStep of the SAPFioriFlows framework is responsible for showing the initial screen of the app to the end user, while simultaneously checking a list of ConfigurationProviders to discover:

1. If there are already configuration parameters available in the app bundle–the plist case, or if an external source should be queried for the configurations
2. If external source(s) should be queried, which?  UI is currently supported for invoking the Discovery Service, QR Scanner, or both
3. Execute the query, when initiated by the user.  For Discovery Service, this is when the user has entered their email, and clicked ‘submit’.  For QR Scanner, this is when the user clicks ‘Scan’, to display the scanner.

When a configuration payload is returned by one of these providers, it should be put through a ConfigurationTransformer.  The default one supplied by SAPFoundation framework and used in the Assistant-generated app is DiscoveryServiceConfigurationTransformer, and it is generally suitable for handling configuration payloads from both Discovery Service, and QR Code scanning.

The SAP Cloud Platform SDK for iOS Assistant generates reusable boilerplate code for this procedure in OnboardingFlowProvider.swift (version 3.1.x) or OnboardingManager.swift (version <3.1) that is optimized for Discovery Service.

Fortunately, because the Discovery Service and QR Scanner cases are quite similar, modifying the generated code to support QR scanning is a trivial two-step operation:

• Supply a JSONConfigurationProvider() instance to the WelcomeScreenStep constructor’s providers array
• In the welcomeScreenCustomizationHandler, set the configurationOptions option set property to include .barcodeScanner

Both of these are minor edits to the configuredWelcomeScreenStep() function.

private func configuredWelcomeScreenStep() -> WelcomeScreenStep {
    
    let discoveryConfigurationTransformer =
        DiscoveryServiceConfigurationTransformer(applicationID: "com.i826181.opportunities",
                                                 authenticationPath: "com.i826181.opportunities")
    let welcomeScreenStep =
        WelcomeScreenStep(transformer: discoveryConfigurationTransformer,
                          providers: [JSONConfigurationProvider()])
    
    welcomeScreenStep.welcomeScreenCustomizationHandler = { welcomeStepUI in
        welcomeStepUI.headlineLabel.text = "My App Name"
        welcomeStepUI.detailLabel.text = "Localized App Description"
        
        if let welcomeScreen = welcomeStepUI as? FUIWelcomeScreen {
            welcomeScreen.configurationOptions = .barcodeScanner
        }
    }
    return welcomeScreenStep
}

Scanning the QR Code

On an iOS simulator (for devices with the camera), add the QR code png from above to the simulator’s camera roll.  On pressing ‘Scan’, the user is presented with the scanner, and they should click the ‘camera roll’ icon at the bottom of the screen to launch the image picker.  Select the QR code image.

On iOS device, the camera roll option is also valid, but typically, the user would center the QR code in the scanner guides, and the scanner will automatically read the QR code when recognized.

On success, the user should see a confirmation view, and then moved forward to the next step in the on boarding sequence.