var host = window.secondscreenHost;
/* ... or use noConflict() to not clobber a previously defined secondscreenHost global. */
var host = window.secondscreenHost.noConflict();
Access
Access to the global defined Second Screen Host instance.
var host = window.secondscreenHost;
/* ... or use noConflict() to not clobber a previously defined secondscreenHost global. */
var host = window.secondscreenHost.noConflict();
Invocation
Start the Second Screen Host using secondscreenHost.start() with an optional custom configuration.
/**
* Starts the Second Screen Host with default and overwritten configuration values.
* @param {Object} config Optional configuration to start the Second Screen Host.
*/
secondscreenHost.start({
Default Values and Customization
The Second Screen Host is configured with default values that can be overwritten by providing a custom configuration on start(). Listed here - aside from the custom design defined - are the default values.
/**
* The Name of the Host Application.
* @type {String}
*/
name: 'Red5 Pro Second Screen Host Example',
/**
* The maximum amount of players (device connections) during a session.
* @type {Number}
*/
maxPlayers: 1,
/**
* The registry endpoint on which your Host and Clients will register their Location
* @type {String}
*/
registryAddress: '10.0.0.1',
/**
* The application Id associated with Second Screen Host in registry.
* @type {String}
*/
appId: 'secondscreen',
/**
* The location of the Flash fallback SWF.
* @type {String}
*/
swfUrl: 'swf/secondscreenHost.swf',
/**
* Location of the SWFObject library used to embed Flash fallback SWF.
* @type {String}
*/
swfobjectUrl: 'swf/swfobject.js',
/**
* Minimum version of Second Screen Host support.
* @type {Object}
*/
minimumVersion: {
major: 0,
minor: 0
},
Control Modes and Custom Design Layout
The following options are available for providing custom control schemes:1. HTML Scheme
An HTML scheme can be provided to connected devices to load a custom control scheme using markup.
The URL is relative to the location of the host application which needs to be served over HTTP/HTTPS.
/**
* These are mutually inclusive. If it is desired to use a custom HTML scheme,
* the proper controlMode must be provided.
*/
controlMode: host.ControlModes.HTML,
controlsUrl: "scheme/basic-scheme.html",
3. DPAD
Setting GAMEPAD with layout.type set to dpad will tell the Client to render the controller as a standard DPAD
/**
* These are mutually inclusive. If it is desired to provide a custom design without using HTML,
* the proper controlMode must be provided
*/
controlMode: host.ControlModes.GAMEPAD,
design: {
orientation: 'portrait',
layout: [{
type: "dpad",
x: 0,
y: 0,
width: 320,
height: 480
}]
}
Additonally, delegate methods can be defined to by invoked upon fault and completion of start().
/**
* Optional delegate to be invoked if a fault has occured upon secondscreenHost.start().
* @param {string} type Enumerable on host.ErrorTypes
* @param {string} message Optional human-readable message explaining error.
*/
error: function(type, message) {},
/**
* Optional delegate to be invoked upon success of secondscreenHost.start().
*/
success: function() {}
});
Events
The Second Screen Host sends notifications related to device connection and message communication.
The following some common examples of events of interest to developers of applications and games integrating Second Screen.
usage
Utilizing a familiar observable syntax, you can subscribe and unsubscribe to event notifications using:host.on(<string>, <function>);
host.off(<string>, <function>);
The available event types to listen to are enumerated on host.EventTypes.
host event types
The following events are associated with the Second Screen host and its recognition in the registry./**
* Notified upon host connection to registry.
* @param {Object} event Provides unique id and color assignment.
*/
host.on(host.EventTypes.SHOW_SLOT_COLOR, function(event) {
var id = event.slotId,
color = event.color;
});
device event types
The following events are notified in relation to device connections associated to the Second Screen host./**
* Notified on each device connection.
* @param {Object} event Provides Device information.
*/
host.on(host.EventTypes.DEVICE_CONNECTED, function(event) {
var device = event.device;
});
/**
* Notified on each device disconnection.
* @param {Object} event Provides Device information.
*/
host.on(host.EventTypes.DEVICE_DISCONNECTED, function(event) {
var device = event.device;
});
device sensor event types
The following event types are associated the sensor capabilties of a device./**
* Notified on recognition to change of orientation on a connected device.
* @param {Object} event Provide Device information and orientation value ('portrait', 'landscape').
*/
host.on(host.EventTypes.ORIENTATION, function(event) {
var device = event.device,
orientation = event.orientation;
});
/**
* Notified on recognition to change of acceleration on a connected device.
* @param {Object} event Provide Device information and acceleration value.
*/
host.on(host.EventTypes.ACCELERATION, function(event) {
var device = event.device,
acceleration = event.acceleration;
});
/**
* Notified on recognition to change of gyroscope on a connected device.
* @param {Object} event Provide Device information and gyroscope value.
*/
host.on(host.EventTypes.GYROSCOPE, function(event) {
var device = event.device,
gyroscope = event.gyroscope;
});
/**
* Notified on recognition to shake of connected device.
* @param {Object} event Provide Device information.
*/
host.on(host.EventTypes.SHAKE, function(event) {
var device = event.device;
});
/**
* Notified on recognition of touch start on a connected device.
* @param {Object} event Provide Device information and touch properties.
*/
host.on(host.EventTypes.TOUCH_START, function(event) {
var device = event.device,
x = event.x,
y = event.y,
id = event.id;
});
/**
* Notified on recognition of touch move on a connected device.
* @param {Object} event Provide Device information and touch properties.
*/
host.on(host.EventTypes.TOUCH_MOVE, function(event) {
var device = event.device,
x = event.x,
y = event.y,
id = event.id;
});
/**
* Notified on recognition of touch end on a connected device.
* @param {Object} event Provide Device information and touch properties.
*/
host.on(host.EventTypes.TOUCH_END, function(event) {
var device = event.device,
x = event.x,
y = event.y,
id = event.id;
});
Device Access and Interface
Single device access is available from getDeviceById() with an id of a registered device.TIP
The connection and disconnection of devices can be monitored by adding listeners to host.EventTypes.DEVICE_CONNECTED and host.EventTypes.DEVICE_DISCONNECTED, respectively, as described previously.
/**
* Returns a Device instance.
* @param {String} deviceId The unique deviceId
* @returns {Device} The associated device found on the Second Screen host OR undefined if not found
*/
var device = host.getDeviceById(deviceId);
/**
* A device can be interacted with directly if required. getDeviceById() returns a Device object with the following API:
*/
Device = {
/**
* Unique identifier assigned upon connection.
* @type {String}
*/
id: 'foo',
/**
* Name assigned upon connection.
* @type {String}
*/
name: 'bar',
/**
* Returns mutable control scheme object that can be resubmitted to update device gamepad screen.
* @return {Object}
*/
editDesign: function() {},
/**
* Vibrates device controller.
*/
vibrate: function() {},
/**
* Enables or disables touch sensor.
* @param {boolean} value
*/
setTouchEnabled: function(value) {},
/**
* Returns enabled state of touch sensor.
* @return {boolean}
*/
getTouchEnabled: function() {},
/**
* Sets the interval to poll for touch sensor.
* @param {float} value
*/
setTouchInterval: function(value) {},
/**
* Returns the interval touch sensor is polled.
* @return {float}
*/
getTouchInterval: function() {},
/**
* Similar to the Touch sensor API defined above,
* mutable methods for enablement and interval are exposed
* for all sensor types:
*
* - Touch
* - Gyro
* - Orientation
* - Accelerometer
*/
};
All Device Control
Along with accessing and interfacing with a single device using getDeviceById(), all connected devices can be interacted with using allDevices()./**
* Returns proxy Device interface that allows for invocation on each connected devices.
* All API methods described in the previous section are available to be interfaced with.
*/
host.allDevices();
/**
* @example Enables touch on all devices.
*/
host.allDevices().setTouchEnabled(true);
/**
* @example Sets mode to navigation control on all connected devices.
*/
host.allDevices().setMode(host.ControlModes.NAVIGATION);
Logging
The log attribute provides a basic means of logging information related to the following levels enumerated on host.LogLevels:/**
* Access to custom logger.
* @type {Logger}
*/
host.log;
host.log.info('Hello, world!');
host.log.debug('Why?');
host.log.warn('Uh-oh!');
host.log.error('Something went horribly wrong :(');
The level of the logger can be defined using setLogLevel(). Anything logged with a lower level than the one provided will NOT be printed in the console.
host.setLogLevel(host.LogLevels.WARN);
To turn off all logging (default)
host.setLogLevel(host.LogLevels.NONE);
Stop
Though the Second Screen host will be shutdown by default when closing the browser or navigating away, the current session can also be stopped explicitly./**
* Shuts down the Second Screen host.
*/
host.stop();