API definition for custom authentication scripts in MSB App
npm install @mobisysgmbh/msb-custom-auth-apiThis package contains Custom Authentication API Contract files needed to develop Custom Authentication Scripts for Mobisys MSB App.
``ts`
export interface CustomAuthApi {
http: CustomAuthHttpClient;
logger: CustomAuthLogger;
appLauncher: CustomAuthAppLauncher;
cookieStorage: CustomAuthCookieStorage;
appInfo: CustomAuthAppInfo;
deviceInfo: CustomAuthDeviceInfo;
versionInfo: CustomAuthVersionInfo;
nfc: CustomAuthNfc;
// MSB App >= 3.14
urlProcessor: CustomAuthUrlProcessor;
// MSB App >= 3.15
scanning: CustomAuthScanning;
// MSB App >= 3.16
foregroundHttp: CustomAuthForegroundHttp;
}
Contains available native modules
`ts`
export interface CustomAuthentication {
login(profile: CustomAuthProfile): Promise
logout(profile: CustomAuthProfile): Promise
}
Interface that has to be implemented as a authentication script
`ts
export interface AuthConfig {
headers: Record
authOptions?: AuthOptions;
}
export interface AuthOptions {
msbAuthentication: 'basic' | 'secureSession' | 'clientCert';
useCustomHeaders: boolean;
}
`
AuthConfig consists of two parts. Headers and AuthOptions. The headers contain the headers that are to be used for further MSB communication.
AuthOptions configures whether further MSB authentication should be carried out afterwards. To do this, select the desired authentication ‘basic’ | ‘secureSession’ | ‘clientCert’ and whether the MSB header or the header of the custom authentication should be used
`ts`
interface CustomAuthProfile
exposes MSB App settings. Those are readonly and can not be changed.
`ts`
interface ScriptSettingsDescriptor
Interface that describes the data structure the MSB App expects for script settings.
It consists of two parts. A mandatory hide credentials script item and an optional array of script items.
`ts`
export interface HideCredentialInputsScriptItem {
key: 'hideCredentialInputs';
description: 'Hide credential inputs';
readonly dataType: 'Boolean';
readonly uiType: 'Checkbox';
readonly defaultValue: boolean;
}
`ts`
export type ScriptItem =
| BooleanScriptItem
| EnumScriptItem
| NumberScriptItem
| StringScriptItem;
The hide credential inputs script item controls the visibility of credential inputs in the MSB App Login Screen.
The array of script items represents script settings that should be used in addition to MSB App settings.
A separate UI is generated in the MSB App for these settings.
getAppName(): Promise
Returns the name of the app. Most likely "MSB App" unless Mobisys changes the name.
getPackageName(): Promise
Returns the package name of the app - the reversed domain name app identifier like com.example.appname
getVersionCode(): Promise
Returns the build identifier of the app
getVersionNumber(): Promise
Returns the version number of the app
launchByUri(uri: string): Promise
Launches a App by URI. 'https://google.com' would start the browser and open googles website. 'slack://open?team={1234}' would open slack app and go to team chat with team id 1234
setCookie(url: string, cookie: string): Promise
Sets a cookie for a specific url. Cookies are cleared after each log out off an MSB application.
isAndroid(): Promise
isIOs(): Promise
isIPad(): Promise
isElectron(): Promise
isWindows(): Promise
Those can be used to check the platform.
getUserAgent(): Promise
Returns current user agent string of current WebView depending on platform.
getDeviceName(): Promise
Returns user-friendly name of the device.
getOem(): Promise
Returns the manufacturer
getOs(): Promise
Returns OS name and version
getPlatformName(): Promise
Returns the device's operating system name.
getDeviceDescription(): Promise
On mobile platforms returns model name. On Desktop returns current user name.
getSerial(): Promise
Tries to retrieve the serial number on mobile platforms. On Desktop returns the uid.
getUsername(): Promise
Not supported on mobile platforms. Throws error. On Desktop retruns the user name.
getUuid(): Promise
Get the device's Universally Unique Identifier. The details of how a UUID is generated are determined by the device manufacturer and are specific to the device's platform or model.
The UUIDs aof a device are not guaranteed to be the same over the lifetime of a device. Sometimes new IDs are generated on factory resets or depending
isScopedStorageEnabled(): Promise
Checks wether scoped storage is enabled on Android. This is always the case from SDK Level 30. Retruns false on other platforms.
cordovaVersion(): Promise
Returns the version of Cordova running on the device.
Allows sending HTTP Get and Post requests.
get({ url, headers }: GetParams): Promise
Sends a HTTP GET request to provided url containing provided headers. ResponseType is set to text.
getArrayBuffer({ url, headers }: GetArrayBufferParams): Promise
Same as get but ResponseType is ArrayBuffer.
getBlob({ url, headers }: GetBlobParams): Promise
Same as get but ResponseType is Blob.
post({ url, headers, body }: PostParams): Promise
Sends a HTTP POST request to provided url containing provided headers and body. Body has to be a string.
postArrayBuffer({ url, headers, data }: PostArrayBufferParams): Promise
Same as post but data has to be an ArrayBuffer.
log(...message: unknown[]): Promise
error(...message: unknown[]): Promise
warn(...message: unknown[]): Promise
info(...message: unknown[]): Promise
debug(...message: unknown[]): Promise
Use these to write logs to log files of MSB App. The log levels are set in MSB App settings.
Provides build time meta data.
getVersionString(): Promise
Returns MSB App version.
getBuildNumber(): Promise
Returns MSB App build number.
getFullVersionString(): Promise
Returns both version and build number in one string.
getDateString(): Promise
Returns the date on which app was built. In ISO 8601 format.
getYearNumber(): Promise
Returns the year in whcih app was built.
getSapVersion(): Promise
Returns current MSB App version in SAP readable format. String length max 4.
isLocalBuild(): Promise
Returns if the MSB App was build localy on a dev machine.
getOssLicenseURL(): Promise
Returns the URL to Open Source Software Licenses.
Provides data from NFC tag scans.
startNfcCapture(captureDataHandler: (data: string) => void): Promise
Provides scanned data to a handler. Handler is called on each new scan.
stopNfcCapture(): Promise
Stops data capturing.
setHandler(handler: CustomAuthAppUrlHandler
Sets a handler that is called on deeplink calls of _msbapp://v1/authentication/customauth/v1_ or _http://msbapp.mobisys.com/v1/authentication/customauth/v1_. The data returned by the handler depends on the query parameters of the called url, but is always a Record
_msbapp://v1/authentication/customauth/v1?param1=paramOne¶m2=paramTwo...¶mN=paramN_ would result in following object beeing returned:
`ts`
{
param1: 'paramOne'
param2: 'paramTwo'
...
paramN: 'paramN'
}
clearHandler(): void
Removes all handlers
enableScanning(params: ScanningParams): Promise
Enables the scanning method that is currently selected in the app settings.
`ts`
export interface ScanningParams {
scanDataHandler: ScanDataHandler;
scanButtonPosition?: ScanButtonPositionParams;
config?: ScanConfig;
}
_scanDataHandler_ - handler which receives the data scanned and the barcode type
`ts`
type ScanDataHandler = (data: string, type: string) => void;
_config_ - configuration for hardware scanner integration such as Zebra and Honeywell etc.. This is documented in user documentation of the EDT component on mobisys portal
Camera Scanning
_scanButtonPosition_ - contains configuration for scan button placement
- _targetElement_ - defines the target HTML element where the scan button should appear
- _scanButtonDimensionsFactor_ - determines the size of scan button
- _mode_ - sets positioning strategy.
`ts`
export type ScanButtonPositioningMode =
| 'Above'
| 'Below'
| 'Dynamic'
| 'Fixed'
| 'Hidden';
_Above_ and _Below_ positions scan button above or below the target element. _Dynamic_ switches between these two dependent on available space around the target element. _Fixed_ positions the button in the upper right corner of the screen and is much bigger than the other options.
_Fixed_ is the default setting if no scanButtonPosition is provided.
disableScanning(): Promise
Disables scanning
foregroundHttp: CustomAuthForegroundHttp
Provides methods for polling HTTP endpoints in the foreground. Available in MSB App >= 3.16.
- pollWithHttpGet(pollingInterval: number): void
Starts polling with HTTP GET requests at the specified interval (in milliseconds).
- stopPollingWithHttpGet(): Promise
Stops the polling process.
Use this module to perform periodic HTTP GET requests while the app is in the foreground, for example to check authentication or session status.