Peripheral device integration

This section provides information about setting up integration between the Sterling Store Engagement application and peripheral devices such as barcode scanners.

About the Sterling Store Engagement application

Sterling Store Engagement is a web-based application that provides users with a feature-rich interface to ensure an efficient and seamless store management experience. It is developed using HTML5, AngularJS, and Bootstrap CSS and can be used on a host of devices.

Need for integration with peripheral devices

Most of the store operations involve scanning barcodes for products, coupons, and so on. Additionally, the Sterling Store Engagement application must interact with payment devices, respond to notifications, and so on. Therefore, it is necessary that IBM Store Engagement application responds to events from external devices/services such as scanners, and so on.

Solution

Only applications that are native to a device or a platform can communicate directly with peripheral devices such as barcode scanners. However, hybrid applications make it possible to embed standard web applications inside a native container so that they can communicate with external devices. Therefore, we can embed the Sterling Store Engagement application inside a native wrapper application using hybrid technology.

Supporting features in the application

To support integration with peripheral devices, the application provides the following components by default:

iscBarcodeScanner service: It provides a utility method called placeBarcodeToElement to pass the barcode data to the application screens.
iscBarcodeScanner directive: It can be used as an attribute to the input field for listening to barcode scanner events. Refer to the JavaScript™ documentation for more information.
iscCordova provider: It provides a utility method called registerPluginInitialization to register the plugin initialization code.
iscPrint service: It provides a utility method called printHtmlOutputCustom which can be used to handle printing with a custom logic.

Creating a hybrid application using Apache Cordova

Note: The application was tested on Android and iOS platforms and not Windows™.

Setting up the environment

Ensure that you have installed 17.3 or later version of the Sterling Store Engagement application.
Download and install Node.js. For more information, see https://nodejs.org/en/download/.
Note: The feature has been tested with Node.js version 5. However, you can use the latest version of Node.js at the time of setting up your environment.
Install the latest version of Apache Cordova. For more information, see the platform-specific instructions available at https://cordova.apache.org/docs/en/latest/.
Install platform-specific tools. For example, Xcode for iOS platform and Android SDK for Android platform.

Setting up Cordova project

Create a workspace folder.
```
cd <cordova_project_container_folder>
```
Create a Cordova project.
```
cordova create <project_name> <package_name> <folder_name>
```
For example, cordova create StoreAppDemo com.ibm.ise.StoreAppDemo StoreAppDemo

Install platforms.

cordova platforms add ios
cordova platforms add android

Note: Specify version, if required.

Install Cordova plugins.
```
cordova plugin add cordova-plugin-device
cordova plugin add cordova-plugin-console
```
1. Install the base plugins if required. For more information, visit Cordova Plugins
2. Install peripheral device plugins.
  Note: Contact peripheral device vendor for drivers and Cordova plugins.
Modify the Cordova config.xml file present in the <project_folder> as follows:
1. Set the value of src attribute in the content element to point to the application URL. For example,
```
<content src="http://localhost:8080/wscdev/store/login.do?landingpage=customerservice"/>
```
2. Update the following elements appropriately to allow the application to access the URLs:
```
<allow-navigation href="http://*/*" />
<allow-navigation href="https://*/*" />
<allow-intent href="http://*/*" />
<allow-intent href="https://*/*" />
```
  Note: If the application should access only certain URLs, then instead of *, provide the URLs.
3. Set an appropriate value for AppendUserAgent to load platform-specific Cordova plugins.
```
<preference name="AppendUserAgent" value="<UserAgentName>" />
```
  Note: The <UserAgentName> should have "cordova" as the prefix. For example, cordova-ios, cordova-android.
4. Configure the project settings, if specified by the plugins provided by peripheral-device vendors.
5. Follow any additional instructions provided by the plugins that you have installed.
Build and deploy the application on the device. For more information, see

Application-side changes

Note:

The angular minification process considers only the following folders under the directory <Runtime>/extensions/wsc/webpages/ngstore/:

jsps, shared, store

Therefore, ensure that your custom code and folders are present in any one of the mentioned folders. In the code snippets provided in this section, let us consider shared, which should be created, if not already.

Copy the contents of <cordova_project folder>/platforms/<platform>/platform_www to the <Runtime>/extensions/wsc/webpages/ngstore/shared/<UserAgentName> folder.
Notes:
- UserAgentName is the value set for the AppendUserAgent preference in config.xml.
- If you are creating the project for multiple platforms, repeat the step for each platform.

Add entries in customer_overrides.properties for loading the cordova plugin files.

yfs.wsc.cordova.supportCordovaApp=Y
yfs.wsc.cordova.useragent.<UserAgentName>=./shared/<UserAgentName>/cordova.js

For example:

yfs.wsc.cordova.useragent.cordova_android=./shared/cordova_android/cordova.js
yfs.wsc.cordova.useragent.cordova_ios=./shared/cordova_ios/cordova.js

Note: If you are hosting the cordova plugins on a different server, then you can provide the appropriate URL.

For example:


yfs.wsc.cordova.useragent.<UserAgentName> = <baseurl>/<UserAgentName>/cordova.js

Add the store-cordova-<feature/plugin>.config.js in the <Runtime>/extensions/wsc/webpages/ngstore/store/config folder

Example : store-cordova-barcode.config.js

angular.module("store").config(["iscCordovaProvider",function(iscCordovaProvider){
    // Cordova initialization start
    iscCordovaProvider.registerPluginInitialization(["iscBarcodeScanner",function(iscBarcodeScanner){
        if(<check for plugin available>){
            //Initialize the corova barcode plugin if necessary
            // Configure the barcode plugin settings to call a method on barcode scan
            // Refer the plugin documentation for acessing the barcode data.
            // call iscBarcodeScanner.placeBarcodeToElement method pass bardcode data for application
            // eg iscBarcodeScanner.placeBarcodeToElement(data.barcode);
        }
    }]);
}]);

Build and deploy the customizations. For more information, see Deploying and deploying customizations.