API Sending data

Use the COUCHFRIENDS.send() function to send data to your connected players. send() always required a json object and should at least contain topic, action and data.

Limitations

The limit of requests you can send to the Websocket server is 60 per minute. Receiving data is currently not limited.

game.host - Host a new game

var dataJson {
    topic: 'game',
    action: 'host'
    data: {
        sessionKey: 'abc' // Optional. Needed for unlocking achievements
    }
}

player.identify - Change to color of the player

When you play games with 2 or more playes people can get confused playing the same-like characters/objects on the big screen. You can identify different players by assigning colors to them.

var dataJson {
    topic: 'player',
    action: 'identify'
    data: {
        id: 1234,
        color: '#ff9900' // Change the color of the player's controller
    }
}

interface.buttonAdd - Display a button

Add a button on the players controller.

/**
 * Example of sending a button to the controller
 * @param topic {string} 'interface'. We changing the players interface.
 * @param action {string} 'buttonAdd'. Adding a button.
 * @param data {object} list with additional settings and options.
 * @param data.id {string} unique identifier of the button. This ID will be send back when the player interact with it.
 * @param data.playerId {int} The id of the player who should see the button.
 * @param [data.type] {string} What kind of button. 'square' or 'circle' are currently supported. Default is 'circle'.
 * @param [data.label] {string} The label to write on the button. Default will be 'A'. Might be empty.
 * @param [data.labelColor] {string} The color of the text of the label. Default '#ffffff'.
 * @param [data.labelFont] {string} The style and size of the font. Default 'bold 22px Arial'.
 * @param [data.color] {string} A hex color code for the background of the button.
 * @param [data.size] {object} Size of the button. Either 'radius' if circle or 'width'/'height' for 'square'.
 * @param [data.size.radius] {int} The radius size in pixels.
 * @param [data.size.width] {int|string} The width in pixels (int) or percentages (string). e.g. '25%'.
 * @param [data.size.height] {int|string} The height in pixels (int) or percentages (string). e.g. '25%'.
 * @param [data.position] {object} The position of the button. Top, left, bottom and right. Int for pixels or string for
 * percentages. e.g. left: '50%' or top: 16.
 */
var jsonData = {
    topic: 'interface',
    action: 'buttonAdd',
    data: {
        id: 'shootBall',
        playerId: 1234,
        type: 'circle',
        label: 'Shoot!',
        labelColor: '#ffffff',
        labelFont: 'bold 22px Arial',
        color: '#ff0000',
        size: {
            radius: 32,
            width: 64,
            height: 64
        },
        position: {
            top: '50%',
            left: '50%',
            bottom: '',
            right: ''
        }
    }
};
COUCHFRIENDS.send(jsonData);

interface.buttonRemove - Removes a button

/**
 * Example of sending a button to the controller
 * @param topic {string} 'interface'. We changing the players interface.
 * @param action {string} 'buttonRemove'. Remove a button.
 * @param data {object} list with parameters.
 * @param data.id {string} unique identifier of the button.
 * @param data.playerId {int} The id of the player where the button should be removed.
 */
var jsonData = {
    topic: 'interface',
    action: 'buttonRemove',
    data: {
        id: 'shootBall',
        playerId: 1234
    }
};
COUCHFRIENDS.send(jsonData);

interface.vibrate - Vibrate controller

/**
 * Example of letting a phone vibrate.
 * @param topic {string} 'interface'.
 * @param action {string} 'vibrate'. Bzzz
 * @param data {object} list with parameters.
 * @param data.playerId {int} The id of the player to vibrate
 * @param data.duration {int} The duration in ms. Maximum 1000ms.
 */
var jsonData = {
    topic: 'interface',
    action: 'vibrate',
    data: {
        playerId: 1234,
        duration: 200
    }
};

game.achievementUnlock - Unlock an achievement

/**
 * Example of letting a phone vibrate.
 * @param topic {string} 'game'.
 * @param action {string} 'achievementUnlock'.
 * @param data {object} list with parameters.
 * @param data.playerId {int} The id of the player to unlock the achievement to
 * @param data.key {string} The key of the achievement.
 */
var jsonData = {
    topic: 'game',
    action: 'achievementUnlock',
    data: {
        playerId: 1234,
        key: 'goal'
    }
};