Introduction

Before proceeding, be sure you know how to create your own JavaScript Interface Asset

To ensure JavaScript Interface Assets work both on Player for Windows and Player for iPad, this protocol has a few limitations - described in this article - that need to be overcome. This is why we created the Intuiface Factory, exposing Intuiface services accessible on all platforms.

Usage

In your JS code, just call the get function of the intuiface object with the name of the service as a parameter:

this.myServiceInstance = intuiface.get("serviceName");

At this moment, the following Factory services are available:

• HTTP request
• Mail as a Service
• File Service
• USB Serial Service

If you can't find a service you want to use in Intuiface, feel free to post your idea to our Ideas Community.

HTTP Service

Name: httpService

Specification

• get(url, headers, callbacks) :invoke a web service using the GET verb. Note that parameters must be passed in the URL.
  • url (string) : URL to call.
  • headers (object) : A JSON object containing the headers parameters,
  • callbacks (object) : callbacks after invocation of the URL.
    • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
    • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.
• post(url, headers, params, callbacks): invoke a web service using the POST verb.
  • url (string) : URL to call.
  • headers (object) : A JSON object containing the headers parameters,
  • params (object) : POST body parameters. Can be a string or a JSON object.
  • callbacks (object) : callbacks after invocation of the URL.
    • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
    • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.
• put(url, headers, params, callbacks): invoke a web service using the PUT verb.
  • url (string) : URL to call.
  • headers (object) : A JSON object containing the headers parameters,
  • params (object) : PUT body parameters. Can be a string or a JSON object.
  • callbacks (object) : callbacks after invocation of the URL.
    • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
    • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.
• patch(url, headers, params, callbacks): invoke a web service using the PATCH verb.
  • url (string) : URL to call.
  • headers (object) : A JSON object containing the headers parameters,
  • params (object) : PATCH body parameters. Can be a string or a JSON object.
  • callbacks (object) : callbacks after invocation of the URL.
    • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
    • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.
• del(url, headers, callbacks): invoke a web service using the DELETE verb. Note that parameters must passed in the URL.
  • url (string) : URL to call.
  • headers (object) : A JSON object containing the headers parameters,
  • callbacks (object) : callbacks after invocation of the URL.
    • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
    • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.

Example

var httpService = intuiface.get("httpService");

var self = this; //to be able to use "this" in the callbacks

httpService.get("http://mywebservice.com/serviceName?param1=value&param2=value", { 
                "success": function(result) {
                 //process your result
                 self.emit('Success', [result]);
                },
                "error" : function(errorMessage) {
                    self.emit('Error', [errorMessage]);
                }});
 
httpService.post("http://mywebservice.com/authenticate", {myHeaderKey: "myHeaderValue"},
                 {key1:"value1",key2="value2"}, { 
                "success": function(result) {
                 //process your result
                 self.emit('Success', [result]);
                },
                "error" : function(errorMessage) {
                     self.emit('Error', [errorMessage]);
                }});

Mail as a Service

Name: mailService

Specifications

• sendMessage(to, subject, body, attachments, callbacks) : send email using Intuiface hosted email service.
  • to (string) : recipient of the message (only one recipient per call)
  • subject (string) : subject of the email
  • body (string) : content of the email. Can be plain text or HTML-formatted.
  • attachments : list of local file paths to attach to the e-mail.
  • callbacks (object) : callbacks after invocation of the mail service.
    • success() is called when the email has been successfully sent.
    • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reasons for failure.

Example

var mailer = intuiface.get("mailService");
  
mailer.sendMessage(to, subject, body, attachments, {
        "success": function () {
             self.emit('MailSent');
        },
        "error": function (errorMessage) 
        {
             self.emit('Error', [errorMessage]);
        }});

File Service

Name: fileService

Usage: this.fileService = intuiface.get('fileService', this);

WARNINGS:

• Do not forget the second parameter in the above call.
• For security reasons imposed by JavaScript, you can only access files and folders located in your Interface Asset folder, e.g. C:\Users\{UserName}\Documents\Intuiface\{XPName}\Files\InterfaceAssets\{MyJS_IA}
• This service cannot be instantiated in your interface asset's constructor and requires a little delay. Here is an example:

var self = this;
    setTimeout(function() {
         this.fileService = intuiface.get('fileService', this);
   }, 500);

Specifications

• read(filePath: string, isBinary: boolean, callbacks: {'success': function, 'error': function}): void: read the content of either a text or binary file
  • parameters:
    • filePath: relative file path (i.e. relative to the experience folder) of the file to be read
    • isBinary: indicates if it's a text file or a binary file (such as an image)
    • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
      • If successful, it will receive as an argument either the text for a text file or the binary content as a byte array (type ArrayBuffer if using Player for Tables/Kiosks, array of bytes if using Player for Windows)
      • If unsuccesful it will receive a displayable error indicating what went wrong
    • return nothing
• write(content: string|ArrayBuffer|Blob, filePath: string, isBinary: boolean, callbacks: {'success': function, 'error': function}): void: write the given content into a file. Content can be text or binary data.
  • parameters:
    • content can either be a string or a binary type such as ArrayBuffer or Blob.
    • filePath: relative file path (i.e. relative to the experience folder) of the file to be written
    • isBinary must be consistent with the given content type and indicate what kind of writing must be applied
    • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
      • , it will not receive any argument
      • If unsuccessful, it will receive a displayable error indicating what went wrong
  • returns nothing
• getFilePath(relativePath: string, callbacks: {'success': function, 'error': function}): string: gets the absolute file path for a file path relative to the experience
  • parameters:If successful
    • relativePath: relative file path (i.e. relative to the experience folder)
    • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
      • If successful, it will receive the displayable path as argument
      • If unsuccessful, it will receive a displayable error indicating what went wrong
  • returns: the absolute file path. Can be assigned, for example, to the "Image" property of the Image asset. This method is synchronous and asynchronous in order to manage calls from the IA (asynchronous) and also internal calls (for the player internal sauce)
• deleteFile(filePath: string, callbacks: {'success': function, 'error': function}): void: delete the given file from its relative path.
  • parameters:
    • filePath: relative file path (i.e. relative to the experience folder) of the file to be deleted
    • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
      • If successful, it will not receive any argument
      • If unsuccessful, it will receive a displayable error indicating what went wrong
  • returns: nothing
• getDirectoryContent(directoryPath: string, calbacks: {'success': function, 'error': function}): array: get the contents of the directory indicated by a relative path
  • parameters:
    • directoryPath: the relative path to the directory whose content is to be listed
    • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
      • If successful, it will receive an array of entries
      • If unsuccessful, it will receive a displayable error indicating what went wrong
  • returns: the list of entries of the directory. Each entry will have the following properties:
    • name: name of the entry
    • isDirectory: boolean indicating if the entry is a directory or not
    • isFile: boolean indicating if the entry is a file or not
    • fullPath: the absolute path of the entry

Samples

Email body formatter

You can download an example of an email body formatting interface asset here. This interface asset will load an HTML template from a file located next to the JavaScript file and will let you generate an email body based on several input parameters.
You can see it in action in our Food Ordering sample.

Folder as a dynamic source for a collection with the FileSystemBrowsingJS Interface Asset

You can use the GetDirectoryContent action to dynamically get the list of objects contained within a folder located next to your Interface Asset in the project file structure. For security reasons, JavaScript prevents fileService from accessing files located outside of this folder.

You can download the FileSystemBrowsingJS sample that will list all the images within a folder named Images located next to your interface asset files.

USB Serial Service

Name: usbSerialService

Usage: this.usbSerialService= intuiface.get('usbSerialService');

WARNINGS:

• This service is only available for Android and BrightSign
• All function option fields are mandatory
• Function option fields marked "ANDROID_ONLY" are additional required values for Android platform.
• Function marked "ANDROID_ONLY" are functions only available on Android platform. 

Specifications

• list(callback): List all devices -- ANDROID_ONLY
  • callback(error, result)
    • error: null if no error happened, otherwise contains an indication of the reason for the failure. 
    • result: array of objects that contains the following device information
      • devicePort
      • deviceID
      • productID
      • productName
      • VendorId
      • serialNumber
      • manufacturerName
      • interfaceCount
• open(opts, callback): Open the serial port
  • opts: Object of options
    • port: Port name.
      • ex for Android: /usb/001/007
      • ex for brightsign: 2
    • baudRate: Transmission speed
    • dataBits: Number of data bits in each character
    • stopBits: Separate each unit of data
    • parity: Method of detecting errors in transmission
    • pid: Product ID -- ANDROID_ONLY
    • vid: Vendor ID -- ANDROID_ONLY
    • driver: Driver name -- ANDROID_ONLY
      • Possible values: FtdiSerialDriver, CdcAcmSerialDriver, Cp21xxSerialDriver, ProlificSerialDriver, Ch34xSerialDriver
    • dtr: Data Terminal Ready -- ANDROID_ONLY
    • rts: Request To Send -- ANDROID_ONLY
    • sleepOnPause: Resume serial port once the application is brought back to foreground -- ANDROID_ONLY
  • callback(error): called when the port is opened
    • error: null if no error happened, otherwise contains an indication of the reason for the failure. 

this.PID = 8963;	// Nexmosphere USB to Serial controller Product ID (for android)
this.VID = 1659;	// Nexmosphere USB to Serial controller Vendor ID (for android)
this.driver = 'ProlificSerialDriver';// Nexmosphere USB to Serial controller Driver name (for android)
this.baudRate = 115200;	// Transmission speed
this.dataBits = 8;	// Number of data bits in each character
this.stopBits = 1;	// Separate each unit of data
this.parity = 0;	// Method of detecting errors in transmission
this.DTR = false;	// Data Terminal Ready
this.RTS = false;	// Request To Send
this.sleepOnPause = true;// Resume serial port once the app is brought back to foreground

Nexmosphere.prototype._open = function (callback) {
    const self = this;
    // Opening serial port
    self._usbSerialService.open(
        {
            port: self.portNameOtherPlatforms,
            pid: self.PID,
            vid: self.VID,
            driver: self.driver,
            baudRate: self.baudRate,
            dataBits: self.dataBits,
            stopBits: self.stopBits,
            parity: self.parity,
            dtr: self.DTR,
            rts: self.RTS,
            sleepOnPause: self.sleepOnPause
        },
        function (error, result) {
            // Handle error
            if (error) {
                return callback(error);
            }
            self._addOutputLog('Port ' + self.portNameOtherPlatforms + ' opened');
            self.isConnected = false;
            // Send an event to refresh view property
            self.emit('isConnectedChanged', [self.isConnected]);
            // Reset counter of auto reconnect
            self.autoReconnectCount = 0;
            // Allow to check connection status
            self.isCheckConnection = true;
            // Start checking connection status
            self._checkConnection();
            callback(null, result);
        }
    );
};