SAP Customer Data Cloud Positions

Native Screen-Sets

Skip to end of metadata
Go to start of metadata

 

Overview

Native Screen-Sets allow your app to maintain the native experience while enjoying the benefits of SAP Customer Data Cloud web Screen-Sets. It is a low-code solution for delivering a highly customizable user interface for a consistent user experience.

While web Screen-Sets are rendered based on an extended version of HTML, Native Screen-Sets are rendered based on a single JSON object.

When designing login, registration and profile update flows for mobile apps, these flows are not only functional but can also as enrich the user's experience in the app itself.

Native Screen-Sets are still in alpha release mode and not yet production-ready. To receive the Native Screen-Set libraries, open a support ticket. The sample apps includes these libraries. 

 

To support Native Screen-Sets, 3 SAP Customer Data Cloud libraries need to be implemented in your Android/iOS project:

Core SDK: for supporting SAP Customer Data Cloud flows on Android & iOS.

Native Screen-Sets library: Connecting the core SDK flows with the Native Screen-Sets engine.

Native Screen-Sets engine library: The engine that will parse the JSON and render the Native Screen-Sets (developed with Google's Flutter framework).

To receive the Native Screen-Sets binaries - please open a support ticket.

Platform Requirements

iOS

  • SAP Customer Data Cloud iOS - Swift SDK v1.1 or above.
  • Apple iOS version 11 or above.
  • XCode version 11.4 or above.

Android

  • SAP Customer Data Cloud Android SDK v 4.1 or above.
  • JAVA8 compatibility is required (update via the application's Gradle script).
  • MinSDK version 16 or above.
  • Android devices running on ARM processors only (99% of devices).

To avoid crashing non ARM devices. Please use the"isSupported()" method of the GigyaNss instance in order to determine if the device can support this feature. Use the web Screen-Sets as a fallback in either Android or iOS .

 

Downloads

Gigya Developer Downloads

 

Integrating the Screen-Sets Engine

iOS - Swift

Download the GigyaNss bundle.

Unzip and place the entire folder into your project folder.

It is important to place the downloaded bundle as is. Do not move files from the GigyaNss bundle, it will break the build.


In order to link the provided debug library:

Go to the "GigyaNss/Debug" folder. Drag both frameworks to the Project -> General -> Frameworks -> Libraries and Embedded Content.

Mark them as Embed & Sign.

Go to Build Settings -> Framework Search Paths and Update GigyaNss/Debug to GigyaNss/$(CONFIGURATION) in both available options (Debug & Release)

If your application contains a custom configuration, update the above code to support your configuration.

Go to Build Phases. Add new Run Script Phase (tap on "+" icon).

Open and then add the following:

bash “${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/GigyaNss.framework/engine.sh” GigyaNss

Check the Run script only when installing option.

Make sure the new script is placed before the Remove unused architectures script that is required for the core SDK setup.

Android

The NSS engine requires your app to declare the following source compatibility in your application's build.gradle file:

android {
    //..
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
     }
}

Unzip the gigya-sdk-nss-engine.zip file and drag the folder to your root application folder.

In your project build.gradle file, add the following (this will allow the application to import the necessary Flutter dependencies and will link the NSS engine as a local reference).:

allprojects {
    repositories {
        google()
        jcenter()
        mavenCentral()
        maven {
            url '../gigya-sdk-nss-engine/host/outputs/repo'
        }
        maven {
            url 'https://storage.googleapis.com/download.flutter.io'
        }
    }
}

Copy the following Android archive libraries into your application's /libs folder and add these references to your application's build.gradle file:

// Referencing the NSS native library.
debugImplementation files('libs/gigya-android-nss-0.1-debug.aar')
releaseImplementation files('libs/gigya-android-nss-0.1-release.aar')

// Referencing the NSS engine.
debugImplementation 'com.gigya.nss.engine:flutter_debug:+'
releaseImplementation 'com.gigya.nss.engine:flutter_release:+'

The NSS libraries are released as debug/release pairs. This is due to various build configurations in the Flutter framework that are built to provide better performance definitions for debug/release builds.


Finally, add the NativeScreensetsActivity.class reference to your application's AndroidManifest.xml file.

<activity
    android:name="com.gigya.android.sdk.nss.NativeScreenSetsActivity"
    android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
    android:hardwareAccelerated="true"
    android:windowSoftInputMode="adjustResize" />

Enabling Native Screen-Sets

In order to start your Native Screen-Sets flow, you are required to provide the JSON file as an application asset (its structure and content will be described in detail below).

Hosting and loading the NSS JSON from the SAP Customer Data Cloud Admin Console is not currently supported.

Android

  • Add the file to your application's assets folder.

iOS 

  • Add the file to your project (does not require special folder placement).

 

iOS - Swift

Add the following line to your AppDelegate.swift class.

GigyaNss.shared.register(scheme: <YOUR_SCHEME>.self)

 To start the NSS flow:

GigyaNss.shared
            .load(asset: "init")
            .initialRoute(name: "login")
            .events(UserHost.self) { result in
                switch result {
                case .success(let screenId, let action, let account):
                    // success
                case .error(let screenId, let error):
                    // error
                case .canceled:
                    // canceled
                }
            }
            .show(viewController: self)

Android

To start the Native Screen-Sets flow:

GigyaNss.getInstance()
        .load("gigya-nss-example.json")
        .initialRoute("register")
        .events(object : NssEvents<MyAccount>() {

            override fun onError(screenId: String, error: GigyaError) {
                // Handle nss exception here.
                GigyaLogger.debug("NSS", "onError")
            }

            override fun onCancel() {
                // Handle nss cancel event if needed.
                GigyaLogger.debug("NSS", "onCancel")
            }

            override fun onScreenSuccess(screenId: String, action: String, accountObj: MyAccount) {
                // Handle login event here if needed.
                GigyaLogger.debug("NSS", "onSuccess for screen: $screenId and action: $action")
            }

        })
        .show(this)

 

Introduction to the Native Screen-Set JSON Schema

In order for the Native Screen-Sets engine to interpret and display the customized screens, we provide a simple JSON based markup language pattern.

This will allow simple to complex UI designs that will grow and facilitate more and more customization tools that will help the application flows to be richer and easier to implement.

Default templates will be provided with each upcoming release in order to give clear reference points.

 

The Root Schema

{
  "routing": {
    "initial": "login",
    "default": {
      "onSuccess": "_dismiss"
    }
  },
  "screens": {
  ...
  }
}

Routing

Initial

  • The screen ID that should be opened by default if not defined explicitly when showing the Native Screen-Sets.

Default

  • The default routing object all screens will inherit from; see the screen component routing below.

Screens

An object map of the Native Screen-Sets screen IDs to their screen component.

Components

The Native Screen-Sets JSON is made from components starting from a collection of screens to the labels, inputs, etc., that are contained within them.

type

  • The type of the component.

textKey

  • The displayed content of the component.

    localization is not currently supported in this release.

bind

  • The path for the Account schema field's 2-way-binding, e.g., for displaying and/or editing the profile.firstName field.

screen

screen component is the root of every displayed screen. It is defined by a unique <screen id> and can perform actions and route to another screen. The screen component is a container component. It may contain children components that stack to create the desired UI. See the container component for more information.

  • appBar
    • Defines the bar at the top of the app.
  • action
    • The screen's target action from the following valid values:
      • login
      • register
      • setAccount
    • The screen's action is invoked via the submit component.
    • The screen's action is invoked with the relevant bound values of the screen's child components.
  • routing
    • By routing from one screen to another, you can use NSS to create a continuous flow of screens.
    • This routing object is made of entries in the following structure: "[event]": "[action]"
      • event
        • If an event is not handled by the screen,
          • it will be handled according to the root's routing.default object;
          • If it is also not handled there, an error will be raised.
        • Valid values:
          • onSuccess
            • when the screen action ends successfully.
      • action
        • Can be either of the following:
          • <screen id>
            • In order to route to the specified screen
          • _dismiss
            • Dismisses (closes) the screen (usually used when a flow is completed).
          • _cancel
            • Dismisses (closes) the screen (usually used to force termination of the screen-set flow before completion).
            • invokes the onCancel event.

 

"login-screen": {
  "routing": {
    "onSuccess": "account-screen"
  },
  "action": "login",
  "appBar": {
    "textKey": "login"
  },
  "stack": "vertical",
  "children": [
    ...
  ]
},
"account-screen": {
  "routing": {
    "onSuccess": "_dismiss"
  },
  "action": "setAccount",
  "appBar": {
    "textKey": "account info"
  },
  "stack": "horizontal",
  "children": [
    ...
  ]
}


submit

The submit component is a button for triggering the screen's action.

  • A single screen component can only have a single submit component.
{
  "type": "submit",
  "textKey": "Submit"
}

 

container

A container component's role is to stack its child components horizontally or vertically.

The screen component extends the container component.

  • stack
    • Defines how children components are stacked.
    • Valid values are:
      • horizontal
      • vertical
  • alignment (optional)
    • Defines how the children components will align to each other within the directional stack.
    • Valid values are:
      • start (default) - Align all children components to the starting (main axis) point of the Container.
      • end - Align all children components to the ending point (main axis) of the Container.
      • center - Align all children components to the center position of the Container.
      • spread - Spread out all children components to the available positions, placing free space evenly between them.
      • equal_spacing - Place all children with even spaces. Including the first and last child component.

 

 {
  "type": "container",
  "stack": "horizontal",
  "alignment": "start",
  "children": [
	...
  ]
}

 

label

The label component displays a text label on the defined field.

  • In addition to the textKey property, it is possible to provide thebind property to allow Account schema binding - with a fallback to the textKey value.

 

 {
  "type": "label",
  "textKey": "Example text"
}

 

textInput

The textInput component allows textual input.

  • textKey
    • Placeholder value
  • Valid type values:
    • text-input
      • Plain text input
    • email-input
      • On focus opens an email keyboard.
    • password-input
      • Masks the content of the field.
{
  "type": "textInput"|"email"|"password",
  "bind": "profile.firstName",
  "textKey": "First name"
}

 

checkbox

The checkbox component shows a checkbox for basic Boolean toggle indication.

{
  "type": "checkbox",
  "bind": "data.terms",
  "textKey": "Accept terms"
}

 

radio

The radio component displays multiple radio button for the user to choose from.

  • options
    • An array of option objects: only one can be default;
    • On selecting an option, its value will be set to the bound Account schema field.
{
  "type": "radio",
  "bind": "data.favGuitar",
  "options": [
    {
      "default": true,
      "value": "PRS",
      "textKey": "Paul Reed Smith"
    },
    {
      "value": "Rubato",
      "textKey": "Rubato Guitars"
    },
    {
      "value": "Parker",
      "textKey": "Parker Guitars"
    }
  ]
}

 

dropdown

The dropdown component displays a drop-down list of options from which the user can choose from.

  • options
    • An array of option objects; only one can be the default;
    • On selecting an option, its value will be set to the bound Account schema field.
 {
  "type": "dropdown",
  "bind": "data.favGuitar",
  "options": [
    {
      "default": true,
      "value": "PRS",
      "textKey": "Paul Reed Smith"
    },
    {
      "value": "Rubato",
      "textKey": "Rubato Guitars"
    },
    {
      "value": "Parker",
      "textKey": "Parker Guitars"
    }
  ]
}

 

Known Issues

Native Screen-Sets engine versioning is still under development.

 

Unable to render {include} The included page could not be found.

 

 

  • No labels