DeviceService

Overview

SERVICE This class is a "service" and it is automatically injected if declared as a member in the constructor of the consuming class. - See the constructor section below for details - See the Automatic Instance Injection page for details on the topic

The DeviceService class provides methods to work device/platform specific features

Properties

No properties

Methods

• logOut

• sync

• hideKeyboard

• isNFCSupported

• readNFCTag

• barcodeScan

• getPlatformType

• getInfo

• openWebBrowser

• takePicture

• selectPicture

• getBTDevices

• beepOk

• beepDoubleOk

• beepError

• location.get

Constructor

Don't instantiate directly instances of the DeviceService.

DeviceService instances are automatically injected by Dynamics Mobile framework.

import { View, SqlQueryService } from '$dms';
import { Customer } from '$dms-bo';

@View()
export class MyView {

  constructor(
    //we need to only declare the member
    private DeviceService: DeviceService
  ){
  
  }

  async load(){      
    //we can now use the injected instance 
    let  location = await this.DeviceService.location.get(0);
    console.log(location.longitude);
  }

}

App Types

📳 Mobile 🌐 Backend

There is a difference in the behaviour of the DeviceService API in mobile and backend apps.

▶️ logOut(): Promise<void>

Description

logOut method performs user logout from the application and navigates to application login screen

Parameters

Returns

void

Example

import { DeviceService } from '@dms';

...
this.DeviceService.logOut();

sync(): Promise<void>

Description

sync method opens the application synchronization screen and performs full synchronization of the app. It can be used only in mobile applications and does not have effect in backend applications.

Parameters

Returns

void

Example

import { DeviceService } from '@dms';

...
this.DeviceService.sync();
// code after the sync method will not be called

hideOnScreenKeyboard(): Promise<void>

Description

hideKeyboard method hides the mobile on-screen keyboard. The method can be used only in mobile apps and does not have effect in backend apps.

Parameters

Returns

void

Example

import { DeviceService} from '@dms';
import { Customer } from '@dms-bo';

...
await this.DeviceService.hideKeyboard();

isNFCSupported(): Promise<boolean>

Description

isNFCSupported method returns true if the mobile device supports NFC ( near field communication). The method can be used only in mobile apps and does not have effect in backend apps.

Parameters

Returns

true if the mobile device supports NFC false if the mobile does not support NFC

Example

import { DeviceService } from '@dms';


...
const supported =  await this.DeviceService.isNFCSupported();
if(supported){
  console.log(`NFC is supported`);
}
else {
 throw new Error(`NFC is not supported`);
}

readNFCTag(): Promise<string>

Description

readNFCTag method activates NFC and tries to read nearby NFC tag and returns the tag reading

Parameters

Returns

string - the content of the NFC tag

Example

import { DeviceService } from '@dms';


...
const tag= await this.DeviceService.readNFCTag();
if(tag){
  console.log(`the NFC tag is ${tag}`);
}
else {
 throw new Error(`NFC reading failed`);
}

barcodeScan(): Promise<{content: string, success: boolean, message: string, format: string }>

Description

barcodeScan method activates the device-camera barcode scanning. It opens the device camera app and allows the user to scan a barcode.

Parameters

Returns

Returns a structure with the following members:

• success: boolean - true if the scanning was successful. If false, the message attribute will contain the reason

• content: string - the barcode which was scanned if success is true

• message: string - error message if success is false

• format: string - format of the barcode

Example

import { DeviceService } from '@dms';


...
const barcode = await this.DeviceService.scanBarcode();
if(barcode.success){
  console.log(`the scanned barcode was ${barcode.content}`);
}
else {
 throw new Error(`Barcode scan failed: ${barcode.message}`);
}

getPlatformType(): Promise<PlatformType>

Description

getPlatformType method returns the type of the platform where the app is running.

Parameters

Returns

The type of the platform where the app is running. See the example for details.

Example

import { DeviceService } from '@dms';

...
const platformType = await this.FileService.getPlatformType()
switch(platformType){
 case PlatformType.Web: 
    console.log('we are running in a web browser');
    break;
 case PlatformType.Android: 
    console.log('we are running in a mobile device under Android OS');
    break;
 case PlatformType.iOS: 
    console.log('we are running in a mobile device under iOS');
    break;
 case PlatformType.Windows: 
    console.log('we are running in a mobile device under Windows 10');
    break;
 case PlatformType.Test: 
    console.log('we are running our code under unit test host, e.g. jest, mocha');
    break;
}

getInfo(): Promise<DeviceInfo>

Description

getInfo method returns system information obtained from the device.

Parameters

Returns

The method returns a structure with the following properties:

• platform: string - the type of the underlying platform (Android, Windows, iOS, Browser)

• version: string - the version if the platform (e.g. operating system version )

• isDevice: string - true if the platform is a mobile device , otherwise it means it is a browser

• isBrowser: string - true if the app is running in a web browder

• isWebview: string - true if the app is running on a mobile device in webview

• shellver: string - the version of the native mobile app.

• webViewVersion: string - the version of the webview

• sdkVersion: string - the version if Dynamics Mobile SDK - e.g. this SDK

• sdkDate: string - the date when the SDK version was released

Example

import { DeviceService } from '@dms';

...
const info = await this.DeviceService.getInfo();
console.log('platform', info.platform);
console.log('version', info.version);
console.log('isDevice', info.isDevice);

if('platofrm'== 'Android')
    console.log('ooops we are running on Android os');   

openWebBrowser(): Promise<void>

Description

openWebBrowser method opens a given url in the default web browser on the device.

Parameters

• url: string - url to be opened in the web browser

Returns

void

Example

import { DeviceService } from '@dms';

...
this.DeviceService.openWebBrowser('https://www.dynamicsmobile.com');

takePicture(): Promise<void>

Description

takePicture method opens the device camera and allows the user to take a picture. The user can confirm or cancel the picture taking. The method returns the url pointing to a selected picture file.

Parameters

• folder: string - the full name of the file folder- myfolder/subfolder

Returns

Returns structure with the following members:

• url: string - points to the file location/name where the camera snapshot was saved.

The method will return null if the user cancels the camera snapshot

Example

import { DeviceService } from '@dms';

...
const picture = await this.DeviceService.takePicture();
if(!picture)
   console.log('user did not take a camera snapshot');
if(picture && picture.url)
   console.log(`the snapshot taken by the user was saved here: ${picture.url}`);

selectPicture(): Promise<{ url: string }>

Description

selectPicture method opens the Picture Selection dialog on the device, where the user can select one picture. The method returns the url pointing to a selected picture file.

Parameters

Returns

Returns structure with the following members:

• url: string - points to the file location/name selected by the user.

The method will return null if the user cancels the picture selection.

Example

import { DeviceService } from '@dms';

...
const picture = await this.DeviceService.selectPicture();
if(!picture)
   console.log('user did not select any picture');
if(picture && picture.url)
   console.log(`user selected the following pciture: ${picture.url}`);

getBTDevices(): Promise<Array<stirng>>

Description

getBTDevices returns a list of with the names of bluetooth devices, currently paired with the mobile device. Can be used in mobile apps only.

Parameters

Returns

void

Example

import { DeviceService } from '@dms';

...
const btDevices = await this.DeviceService .getBTDevices();
if(btDevices.length==0)
   console.log('There are no paired BT devices, currently!');

beepOk(): Promise<void>

Description

beepOk method plays a short ok-alike sound on the mobile device. Can be used in mobile apps only. Can be used after successful operations like successful barcode scan for example.

Parameters

Returns

void

Example

import { DeviceService } from '@dms';

...
await this.DeviceService.beepOk();

beepDoubleOk(): Promise<void>

Description

beepDoubleOk method plays a two times ok-alike sound on the mobile device. Can be used in mobile apps only. Can be used after successful operations like successful barcode scan for example.

Parameters

Returns

void

Example

import { DeviceService } from '@dms';

...
await this.DeviceService.beepDoubleOk();

beepError(): Promise<void>

Description

beepError method plays a short error alike sound on the mobile device. Can be used in mobile apps only. Can be used after successful operations like successful barcode scan for example.

Parameters

Returns

void

Example

import { DeviceService } from '@dms';

...
await this.DeviceService.beepError();

location.get(precision:number): Promise<{latitude: number; longitude: number; speed: number; accuracy: number;}>

Description

location.get method obtains the current device geographic location from the device's location subsystem like GPS, WiFi or Cellular network.

Parameters

• precision: number - not used as of now, please provide 0 for future compatibility

Returns

A flat structure with the following members:

• accuracy: number - not used as of now

• longitude: number - the longitude segment of the current geo location of the device

• latitude: number - the latitude segment of the current geo location of the device

• speed: number - the current speed of the mobile device

Example

import { DevieService } from '@dms';

...
const location = await this.DeviceService.location.get(0);
if(location && location.latitude!=0){
  console.log('longitude: ', location.longitude);
  console.log('latitude: ', location.latitude);
}
else {
  throw new Error('Please check if location services are enabled and try again!');
}