Skip to content

Discovery Service Onboarding

If you use discovery service based onboarding then the end user has to fill out an email address field on the UI, in order to specify where the discovery service is located. This information will be handed over to the app, the app's responsibility to locate the discovery service, query the data and to execute the onboarding based on the data provided by the discovery service. This happens on Activation screen after is pressed the primary button and it navigates to activation screen.

Add Launch screen activity to your manifest file

The LaunchScreenActivity and the ActivationActivity should be added to the AndroidManifest.xml file in an activity xml tag. It is required to specify also the "action_handler" meta-data tag for the launch screen (the same way as in case of the standard onboarding).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
        <activity
            android:name="com.sap.cloud.mobile.onboarding.launchscreen.LaunchScreenActivity"
            android:label="@string/app_name"
            android:theme="@style/Theme.AppCompat.Light.NoActionBar">
            <meta-data
                android:name="action_handler"
                android:value="<your_package_name>.WelcomeScreenActionHandlerImpl" />
        </activity>
        <activity
            android:name="com.sap.cloud.mobile.onboarding.activation.ActivationActivity"
            android:label="@string/app_name"
            android:theme="@style/AppTheme.NoActionBar"
            android:parentActivityName="com.sap.cloud.mobile.onboarding.launchscreen.LaunchScreenActivity">
            <meta-data
                android:name="android.support.PARENT_ACTIVITY"
                android:value="com.sap.cloud.mobile.onboarding.launchscreen.LaunchScreenActivity" />
        </activity>

Start the LaunchScreenActivity

The LaunchScreenActivity can be started with standard startActivityResult method of the Activity and you can configure it via the LaunchScreenSettings class. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
        Intent i = new Intent(getIntent());
        i.setComponent(new ComponentName(
                getPackageName(),
                "com.sap.cloud.mobile.onboarding.launchscreen.LaunchScreenActivity"));
        LaunchScreenSettings settings = new LaunchScreenSettings();
        settings.setLaunchScreenHeadline("Welcome");
        ...
        settings.setWelcomeScreenType(OnboardingType.DISCOVERY_SERVICE_ONBOARDING);
        settings.setDemoAvailable(true);
        settings.saveToIntent(i);

        startActivityForResult(i, LAUNCH_SCREEN);
If you would like to use discovery service based onboarding process, then you should set the type of the welcome screen/launch screen to OnboardingType.DISCOVERY_SERVICE_ONBOARDING as shown in the example above. In this case you have to implement of the startOnboardingWithDiscoveryServiceEmail method of the WelcomeScreenActionHandler interface in your action handler implementation class.

In addition, via the setDemoAvailable method you can specify if the demo mode is supported (that is the "Try the demo" button is visible on the welcome screen). If you enable demo mode, then you have to implement of the startDemoMode method of the WelcomeScreenActionHandler interface in your action handler implementation class as well.

If you would like to customize also the Activation screen, then you have to use its Settings class in addition to the Settings of the launch screen.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
        Intent i = new Intent(getIntent());
        i.setComponent(new ComponentName(
                getPackageName(),
                "com.sap.cloud.mobile.onboarding.launchscreen.LaunchScreenActivity"));
        LaunchScreenSettings settings = new LaunchScreenSettings();
        settings.setLaunchScreenHeadline("Welcome");
        ...
        settings.setWelcomeScreenType(OnboardingType.DISCOVERY_SERVICE_ONBOARDING);
        settings.setDemoAvailable(true);
        settings.saveToIntent(i);
        ActivationSettings activationSettings = new ActivationSettings();
        activationSettings.setTitle("Activation");
        ...
        activationSettings.saveToIntent(i);

        startActivityForResult(i, LAUNCH_SCREEN);
After setting the custom parameters of the activation screen, the result should be saved into the intent of the launch screen, because the activation screen will be started automatically by the launch screen, and all the activation relevant parameters will be handed over to the intent of the activation screen.

Implementation of the callback method for discovery service onboarding

If you need discovery service based onboading process you have to implement of the startOnboardingWithDiscoveryServiceEmail method of the WelcomeScreenActionHandler interface in your action handler implementation class.

The implementation of this method will be executed on a dedicated background thread of the caller activity, more precisely the background thread of the headless fragment of the caller activity. This fragment is handed over to the method as parameter. The second parameter of the callback function transmits the email address typed in by the end user as the address of the discovery service. You can access the caller activity via the getActivity() method of this fragment. Please note that the result of the getActivity call might be null value if there is no active activity in the background, for example due to an ongoing change orientation process.

The callback method waits for response synchronously, so if you need asynchronous communication, then you have to wait on this thread until the async response arrives. You are allowed block the thread because you are on a dedicated background thread.

As a consequence, you have to be prepared to handle the interrupted flag of the thread. For example: if the user taps on the back button, or if the system destroys the caller fragment, then this thread will be interrupted. If the execution of your callback method was successfully interrupted, that is the normal processing was not completed, then you should throw InterruptedException from your implementation in order to indicate that the processing was cancelled. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    @Override
    public void startOnboardingWithDiscoveryServiceEmail(
            Fragment fragment, String userEmail) throws InterruptedException {
        Log.i(TAG, "startOnboardingWithDiscoveryServiceEmail");
        Log.i(TAG, "email:" + userEmail);
        Intent intent = new Intent();

        //process the login synchrounously
        //...
        //
        fragment.getActivity().setResult(Activity.RESULT_OK, intent);
        fragment.setRetainInstance(false);
        fragment.getActivity().finish();
    }

On the other you are also allowed to start new activity on top of the caller activity. Please note that in this case the caller fragment might be destroyed, that is you are not allowed to use the fragment parameter after this point. In addition, the response of the new activity will be called on the caller fragment/activity and therefore you have to implement one more callback method named onActivityResult. For details see the example for the custom onboarding.

The onActivityResult will get a caller fragment again. Please note that this caller instance might be difference from the one you received from the startOnboardingWithDiscoveryServiceEmail.