Contact

Contact

The Contact control interface can be used to control the state of the output contacts (VP330 / EVP380) and to retrieve the state of the input contacts.

The following API is asynchronous and is using Promise to return values.
To use this API, you first need to retrieve the contact control interface thanks to IDAL.getControlInterfaces().

Methods

addListener(listener): Promise.<boolean>

Attach an event handler to the Contact control interface.

Since:
  • firmware v1.08

This method was introduced with firmware version v1.08 to make it possible to run the same code on the player or on a remote browser using IDAL.getRemoteControlInterfaces().
When running on the video player, this method is equivalent to window.addEventListener('idal-contact-event', function(e) {}).

Example
var contact = ... // Get the Contact interface
contact.addListener(function(event) {
    // Here the value of event.type is always 'idal-contact-event'
    var info = event.detail;
    if (info.type == 'input-change' || !info.type) { // Testing !info.type for compatibility with firmware < v1.08
        console.log("Input contact name: " + info.name);
        for (var i = 0 ; i < info.values.length ; i++) {
            console.log("Contact " + i + ": " + info.values[i]);
        }
    }
});
Parameters
Name Type Description
listener Listener

The function to run when a contact event occurs.
Returns

A promise resolved with a boolean value.

Type
Promise.<boolean>

getInputByName(name): Promise.<InputContactInfo> | Promise.<ErrorStatus>

Get the current state of the input contacts.

Input contacts are identified by a name:

  • "standalone" for the single contact available on all players.
  • "combined" for the 8 input contacts available on VP330 and EVP380.

You can also retrieve the contact states in real time thanks to the InputContactEvent event.

Parameters
Name Type Description
name string

Input contact name ("standalone" or "combined").
Returns

removeListener(listener): Promise.<boolean>

Removes an event handler that has been attached to the Contact interface.

Since:
  • firmware v1.08
Parameters
Name Type Description
listener Listener

The function previously attached with addListener()
Returns

A promise resolved with a boolean value.

Type
Promise.<boolean>

setInputConfiguration(config): Promise.<boolean> | Promise.<ErrorStatus>

Set the input contacts configuration (control mode).

Input contact combinations are binded to actions ("play folder" by default) which are automatically managed by the video playback engine.
If you need to override this behavior and control the input contacts from the HTML/JavaScript layer, you have to call this method with config.controller set to 'browser'.

The configuration can be automatically reverted to the default depending on the value of config.lifetime.

This method can also be used to map input contact events to regular keyboard events. It makes it possible to use input contacts as a keyboard and use generic key event handlers such as keyup and keydown.

Example

Usage of input contacts to keyboard events mapping.

// In this example, 'contact' is the variable referencing the contact control interface..
// Configuring input contacts to act as arrows, enter and escape keys...
// The configuration will be reverted when a new page is loaded.
var config = {
    controller: "browser",
    lifetime: "url",
    keymaps: {
        combined: [
            "ArrowLeft",
            "ArrowRight",
            "ArrowUp",
            "ArrowDown",
            "Enter",
            "Escape"
        ]
    }
};
contact.setInputConfiguration(config)
    .then(function(e) {
         // Do what you need here
     })
    .catch(function(e) {
         // Handle error here
    });

// Install keyboard event handler
window.addEventListener("keydown", function(e) {
    console.log("Key down: key=" + e.key + ", code=" + e.code + ", keyCode=" + e.keyCode);
});
Parameters
Name Type Description
config InputContactConfig

The configuration to apply to input contacts.
Returns

  • A promise resolved with a boolean value.

    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

setOutputById(id, value): Promise.<boolean> | Promise.<ErrorStatus>

Set a single output contact state using its identifier.

Parameters
Name Type Description
id number

The contact identifier is a value between 0 and 7.
value number | boolean

The new contact state:

  • 0 or false to open the contact.
  • non zero or true to close the contact.
Returns

  • A promise resolved with a boolean value.

    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

setOutputByMask(value, mask): Promise.<boolean> | Promise.<ErrorStatus>

Set many output contacts at once.

Parameters
Name Type Description
value number

The bitmask of all the output contact values.
One bit per contact.
The least significant bit is the contact number 0.
mask number

The bitmask of the contacts to actually set.
One bit per contact.
The least significant bit is the contact number 0.
Only the contacts having their bit set to 1 are modified.
Returns

  • A promise resolved with a boolean value.

    Type
    Promise.<boolean>

  • A promise rejected with an ErrorStatus.

    Type
    Promise.<ErrorStatus>

Type Definitions

InputContactConfig

Configuration to set on input contacts.
It defines the entity responsible for managing the input contacts: the browser or the video player.
It is also possible to configure the input contact keyboard mapping.

Properties
Name Type Attributes Default Description
controller 'browser' | 'videoplayer'

The name of input contact controller.
It must be set to 'browser' to let the HTML/JavaScript layer control the inputs or 'videoplayer' to let the playback engine handle input contact actions.
lifetime 'url' | 'site' | 'session' | 'scenario' <optional>
 'url'

The configuration lifetime can be set when the controller is the web browser.
This parameter defines when the configuration has to be reverted to video engine control.

ValueDescription
'url' The config is only applied to the current URL and is reverted when:
  • the page location has changed following an hyperlink click or a programmatic change such as a modification of window.location.
  • the page has been reloaded following a programmatic change such as window.location.reload().
  • the playback engine has processed a tag such as [WEBS x] or [WEBE x].
  • the browser has been closed with [WEBS OFF] or [WEBE OFF].
'site' The config is only applied to the current site and is reverted when:
  • the playback engine has processed a tag such as [WEBS x] or [WEBE x].
  • the browser has been closed with [WEBS OFF] or [WEBE OFF].
Here we are referring to an engine site (not an URL) which is loaded using the [WEBS x] or [WEBE x] tags...
'session' The config is applied to the current browser session.
A session is started with [WEBS x] or [WEBE x] tags and is closed with [WEBS OFF] or [WEBE OFF].
The config is reverted when the browser session is closed.
'scenario' The configuration is applied on the current scenario.
It remains active between session (when the browser is closed), sites and URLs.
To make it simple: the configuration stays active until another configuration is explicitly set.
keymaps Object <optional>

Can only be used when controller is set to 'browser'.
Contains the keyboard events associated to each contact.
It makes it possible to handle input contact events as regular keyboard events, using keyup and keydown event handlers.

Properties
Name Type Attributes Description
combined Array.<string> <optional>

The key mapping to use on the combined input contacts. This array must contain a maximum of 8 key names, one for each contact.
standalone Array.<string> <optional>

The key mapping to use on the standalone input contact. This array contains one single key name.

List of available key codes

Hover the mouse over the keys to see their names.

InputContactInfo

A InputContactInfo contains the states of one or more input contacts.

Properties
Name Type Description
name string

The logical name of the input contact group.
values Array.<boolean>

An array of input contact values.

Events

InputContactEvent

InputContactEvent are fired when the state of the input contacts is modified.

Tutorials:
Properties
Name Type Description
type 'idal-contact-event'

The contact event type.
detail Object
Properties
Name Type Description
type 'input-change'

The input change event type.
Note: this property is available since firmware version v1.08.
name string

The logical name of the input contact group.
values Array.<boolean>

An array of input contact values.

This event shall be registered using Contact.addListener().
It can also be registered using window.addEventListener() as defined by the DOM specification.
if you plan to use the remote control interfaces, the later method must be avoided.

Type
Example
// Preferred method: registration using Contact.addListener()
var contact = ... // Get the Contact control interface
contact.addListener(function(e) {
    var info = e.detail;
    if (info.type == 'input-change' || !info.type) { // Testing !info.type for compatibility with firmware < v1.08
        console.log("Input contact name: " + info.name);
        for (var i = 0 ; i < info.values.length ; i++) {
            console.log("Contact " + i + ": " + info.values[i]);
        }
    }
});