Classes

Global

AirConsole

AirConsole

new AirConsole(opts) → {AirConsoleObject}

Your gateway object to AirConsole. There are getter and setter functions for all properties. Do not access properties of this object directly.
Parameters:
Name Type Description
opts AirConsole~Config Constructor config, see bellow.
Source:
Returns:
The AirConsole object.
Type
AirConsoleObject

Members

(static, constant) ORIENTATION_LANDSCAPE :string

The landscape orientation.
Type:
  • string
Source:

(static, constant) ORIENTATION_PORTRAIT :string

The portrait orientation.
Type:
  • string
Source:

(static, constant) SCREEN :number

The device ID of the game screen.
Type:
  • number
Source:

Methods

arePlayersSilenced() → {boolean}

Queries, if new devices are currently silenced.
Since:
  • 1.9.0
Source:
Returns:
True, if new devices that are not players are silenced.
Type
boolean

broadcast(data)

Sends a message to all connected devices.
Parameters:
Name Type Description
data
Source:

convertDeviceIdToPlayerNumber(device_id) → {number|undefined}

Returns the player number for a device_id, if the device_id is part of the active players previously set by the screen by calling setActivePlayers. Player numbers are zero based and are consecutive. If the device_id is not part of the active players, this function returns undefined.
Parameters:
Name Type Description
device_id
Source:
Returns:
Type
number | undefined

convertPlayerNumberToDeviceId(player_number) → {number|undefined}

Returns the device_id of a player, if the player is part of the active players previously set by the screen by calling setActivePlayers. If fewer players are in the game than the passed in player_number or the active players have not been set by the screen, this function returns undefined.
Parameters:
Name Type Description
player_number
Source:
Returns:
Type
number | undefined

editProfile()

Lets the user change his nickname, profile picture and email address. If you need a real nickname of the user, use this function. onDeviceProfileChange will be called if the user logs in.
Source:

getActivePlayerDeviceIds() → {Array}

Returns an array of device_ids of the active players previously set by the screen by calling setActivePlayers. The first device_id in the array is the first player, the second device_id in the array is the second player, ...
Source:
Returns:
Type
Array

getControllerDeviceIds() → {Array}

Returns all controller device ids that have loaded your game.
Source:
Returns:
Type
Array

getCustomDeviceState(device_id) → {Object|undefined}

Gets the custom DeviceState of a device.
Parameters:
Name Type Description
device_id number | undefined The device ID of which you want the custom state. Default is this device.
Source:
Returns:
The custom data previously set by the device.
Type
Object | undefined

getDeviceId() → {number}

Returns the device_id of this device. Every device in an AirConsole session has a device_id. The screen always has device_id 0. You can use the AirConsole.SCREEN constant instead of 0. All controllers also get a device_id. You can NOT assume that the device_ids of controllers are consecutive or that they start at 1. DO NOT HARDCODE CONTROLLER DEVICE IDS! If you want to have a logic with "players numbers" (Player 0, Player 1, Player 2, Player 3) use the setActivePlayers helper function! You can hardcode player numbers, but not device_ids. Within an AirConsole session, devices keep the same device_id when they disconnect and reconnect. Different controllers will never get the same device_id in a session. Every device_id remains reserved for the device that originally got it.
Source:
See:
Returns:
Type
number

getLanguage(device_id) → {String}

Returns the current IETF language tag of a device e.g. "en" or "en-US"
Parameters:
Name Type Description
device_id number | undefined The device id for which you want the language. Default is this device.
Source:
Returns:
IETF language
Type
String

getMasterControllerDeviceId() → {number|undefined}

Returns the device ID of the master controller. Premium devices are prioritzed.
Source:
Returns:
Type
number | undefined

getNavigateParameters() → {*}

Get the parameters in the loaded game that were passed to navigateTo.
Source:
Returns:
Type
*

getNickname(device_id) → {string|undefined}

Returns the nickname of a user.
Parameters:
Name Type Description
device_id number | undefined The device id for which you want the nickname. Default is this device. Screens don't have nicknames.
Source:
Returns:
Type
string | undefined

getPremium()

Offers the user to become a premium member. Can only be called from controllers. If you call getPremium in development mode, the device becomes premium immediately.
Source:

getPremiumDeviceIds() → {Array.<number>}

Returns all device ids that are premium.
Source:
Returns:
Type
Array.<number>

getProfilePicture(device_id_or_uid, size) → {string|undefined}

Returns the url to a profile picture of the user.
Parameters:
Name Type Description
device_id_or_uid number | string | undefined The device id or uid for which you want the profile picture. Default is the current user. Screens don't have profile pictures.
size number | undefined The size of in pixels of the picture. Default is 64.
Source:
Returns:
Type
string | undefined

getServerTime() → {number}

Returns the current time of the game server. This allows you to have a synchronized clock: You can send the server time in a message to know exactly at what point something happened on a device. This function can only be called if the AirConsole was instantiated with the "synchronize_time" opts set to true and after onReady was called.
Source:
Returns:
Timestamp in milliseconds.
Type
number

getTranslation(id, values)

Gets a translation for the users current language See http://developers.airconsole.com/#!/guides/translations
Parameters:
Name Type Description
id String The id of the translation string.
values Object | undefined Values that should be used for replacement in the translated string. E.g. if a translated string is "Hi %name%" and values is {"name": "Tom"} then this will be replaced to "Hi Tom".
Source:

getUID(device_id) → {string|undefined}

Returns the globally unique id of a device.
Parameters:
Name Type Description
device_id number | undefined The device id for which you want the uid. Default is this device.
Source:
Returns:
Type
string | undefined

isPremium(device_id) → {boolean|undefined}

Returns true if the device is premium
Parameters:
Name Type Description
device_id number The device_id that should be checked. Only controllers can be premium. Default is this device.
Source:
Returns:
Returns true or false for a valid device_id and undefined if the device_id is not valid.
Type
boolean | undefined

isUserLoggedIn(device_id) → {boolean}

Returns true if a user is logged in.
Parameters:
Name Type Description
device_id number | undefined The device_id of the user. Default is this device.
Source:
Returns:
Type
boolean

message(device_id, data)

Sends a message to another device.
Parameters:
Name Type Description
device_id number | undefined The device ID to send the message to. If "device_id" is undefined, the message is sent to all devices (except this one).
data
Source:
Request that all devices return to the AirConsole store.
Source:
Request that all devices load a game by url or game id.
Parameters:
Name Type Description
url string The base url of the game to navigate to (excluding screen.html or controller.html). Instead of a url you may also pass a game id. You can also navigate relatively to your current game directory: To navigate to a subdirectory, pass "./DIRECTORY_NAME". To navigate to a parent directory pass "..".
parameters object You can pass parameters to the game that gets loaded. Any jsonizable object is fine. The parameters will be appended to the url using a url hash.
Source:

(abstract) onActivePlayersChange(player_number)

Gets called when the screen sets the active players by calling setActivePlayers().
Parameters:
Name Type Description
player_number number | undefined The player number of this device. Can be undefined if this device is not part of the active players.
Source:

(abstract) onAdComplete(ad_was_shown)

Gets called when an advertisement is finished or no advertisement was shown.
Parameters:
Name Type Description
ad_was_shown boolean True iff an ad was shown and onAdShow was called.
Source:

(abstract) onAdShow()

Gets called if a fullscreen advertisement is shown on this screen. In case this event gets called, please mute all sounds.
Source:

(abstract) onConnect(device_id)

Gets called when a device has connected and loaded the game.
Parameters:
Name Type Description
device_id number the device ID that loaded the game.
Source:

(abstract) onCustomDeviceStateChange(device_id, custom_data)

Gets called when a device updates it's custom DeviceState by calling setCustomDeviceState or setCustomDeviceStateProperty. Make sure you understand the power of device states:
Parameters:
Name Type Description
device_id number the device ID that changed its custom DeviceState.
custom_data Object The custom DeviceState data value
Source:
See:

(abstract) onDeviceMotion(data)

Gets called every X milliseconds with device motion data iff the AirConsole was instantiated with the "device_motion" opts set to the interval in milliseconds. Only works for controllers. Note: Some browsers do not allow games to access accelerometer and gyroscope in an iframe (your game). So use this method if you need gyroscope or accelerometer data.
Parameters:
Name Type Description
data object data.x, data.y, data.z for accelerometer data.alpha, data.beta, data.gamma for gyroscope
Source:

(abstract) onDeviceProfileChange(device_id)

Gets called when a device updates it's profile pic, nickname or email.
Parameters:
Name Type Description
device_id number The device_id that changed its profile.
Source:

(abstract) onDeviceStateChange(device_id, user_data)

Gets called when a device joins/leaves a game session or updates its DeviceState (custom DeviceState, profile pic, nickname, internal state). This is function is also called every time onConnect, onDisconnect or onCustomDeviceStateChange, onDeviceProfileChange is called. It's like their root function.
Parameters:
Name Type Description
device_id number the device_id that changed its DeviceState.
user_data AirConsole~DeviceState the data of that device. If undefined, the device has left.
Source:

(abstract) onDisconnect(device_id)

Gets called when a device has left the game.
Parameters:
Name Type Description
device_id number the device ID that left the game.
Source:

(abstract) onEmailAddress(email_address)

Gets called if the request of requestEmailAddress() was granted. For privacy reasons, you need to whitelist your game in order to receive the email address of the user. To whitelist your game, contact developers@airconsole.com. For development purposes, localhost is always allowed.
Parameters:
Name Type Description
email_address string | undefined The email address of the user if it was set.
Source:

onHighScores(high_scores)

Gets called when high scores are returned after calling requestHighScores. We highly recommend to read the High Score guide (developers.airconsole.com)
Parameters:
Name Type Description
high_scores Array.<AirConsole~HighScore> The high scores.
Source:

onHighScoreStored(high_score)

Gets called when a high score was successfully stored. We highly recommend to read the High Score guide (developers.airconsole.com)
Parameters:
Name Type Description
high_score AirConsole~HighScore | null The stored high score if it is a new best for the user or else null. Ranks include "world", "country", "region", "city" if a high score is passed.
Source:

(abstract) onMessage(device_id, data)

Gets called when a message is received from another device that called message() or broadcast(). If you dont want to parse messages yourself and prefer an event driven approach, @see http://github.com/AirConsole/airconsole-events/
Parameters:
Name Type Description
device_id number The device ID that sent the message.
data serializable The data that was sent.
Source:

(abstract) onPause()

Gets called on the Screen when the game should be paused.
Source:

(abstract) onPersistentDataLoaded(data)

Gets called when persistent data was loaded from requestPersistentData().
Parameters:
Name Type Description
data Object An object mapping uids to all key value pairs.
Source:

(abstract) onPersistentDataStored(uid)

Gets called when persistent data was stored from storePersistentData().
Parameters:
Name Type Description
uid String The uid for which the data was stored.
Source:

(abstract) onPremium(device_id)

Gets called when a device becomes premium or when a premium device connects.
Parameters:
Name Type Description
device_id number The device id of the premium device.
Source:

(abstract) onReady(code)

Gets called when the game console is ready. This event also fires onConnect for all devices that already are connected and have loaded your game. This event also fires onCustomDeviceStateChange for all devices that are connected, have loaded your game and have set a custom Device State.
Parameters:
Name Type Description
code string The AirConsole join code.
Source:

(abstract) onResume()

Gets called on the Screen when the game should be resumed.
Source:

openExternalUrl(url)

Opens url in external (default-system) browser. Call this method instead of calling window.open. In-App it will open the system's default browser. Because of Safari iOS you can only use it with the onclick handler:
Open browser
OR in JS with assigning element.onclick.
Parameters:
Name Type Description
url string The url to open
Source:

requestEmailAddress()

Requests the email address of this device and calls onEmailAddress iff the request was granted. For privacy reasons, you need to whitelist your game in order to receive the email address of the user. To whitelist your game, contact developers@airconsole.com. For development purposes, localhost is always allowed.
Source:

requestHighScores(level_name, level_version, uids, ranks, total, top)

Requests high score data of players (including global high scores and friends). Will call onHighScores when data was received. We highly recommend to read the High Score guide (developers.airconsole.com)
Parameters:
Name Type Description
level_name String The name of the level
level_version String The version of the level
uids Array.<String> | undefined An array of UIDs of the users that should be included in the result. Default is all connected controllers
ranks Array.<String> | undefined An array of high score rank types. High score rank types can include data from across the world, only a specific area or a users friends. Valid array entries are "world", "country", "region", "city", "friends", "partner".
Default is ["world"].
total number | undefined Amount of high scores to return per rank type. Default is 8.
top number | undefined Amount of top high scores to return per rank type. top is part of total. Default is 5.
Source:

requestPersistentData(uids)

Requests persistent data from the servers.
Parameters:
Name Type Description
uids Array.<String> The uids for which you would like to request the persistent data. For controllers, the default is the uid of this device. Screens must provide a valid array of uids.
Version:
  • 1.9.0 - uids is no longer optional for requests from the screen
Source:

setActivePlayers(max_players)

Takes all currently connected controllers and assigns them a player number.
Can only be called by the screen. You don't have to use this helper function, but this mechanism is very convenient if you want to know which device is the first player, the second player, the third player ...
The assigned player numbers always start with 0 and are consecutive. You can hardcode player numbers, but not device_ids.
Once the screen has called setActivePlayers you can get the device_id of the first player by calling convertPlayerNumberToDeviceId(0), the device_id of the second player by calling convertPlayerNumberToDeviceId(1), ...
You can also convert device_ids to player numbers by calling convertDeviceIdToPlayerNumber(device_id). You can get all device_ids that are active players by calling getActivePlayerDeviceIds().
The screen can call this function every time a game round starts.
When using Player Silencing, the screen needs to call this every time a game round starts or finishes.
Calling it with max_players of 1 or more signals the start of the game round while calling it with max_players 0 signals the end of the game round.
Parameters:
Name Type Description
max_players number The maximum number of controllers that should get a player number assigned.
Source:

setCustomDeviceState(data)

Sets the custom DeviceState of this device.
Parameters:
Name Type Description
data Object The custom data to set.
Source:

setCustomDeviceStateProperty(key, value)

Sets a property in the custom DeviceState of this device.
Parameters:
Name Type Description
key String The property name.
value mixed The property value.
Source:

setImmersiveState(immersiveState)

Sets the immersive state of the AirConsole game based on the provided options.
At least one property is required for the immersive state to be set.
Parameters:
Name Type Description
immersiveState ImmersiveOption The immersive state to send.
Source:

setOrientation(orientation)

Sets the device orientation.
Parameters:
Name Type Description
orientation string AirConsole.ORIENTATION_PORTRAIT or AirConsole.ORIENTATION_LANDSCAPE.
Source:

showAd()

Requests that AirConsole shows a multiscreen advertisment. Can only be called by the AirConsole.SCREEN. onAdShow is called on all connected devices if an advertisement is shown (in this event please mute all sounds). onAdComplete is called on all connected devices when the advertisement is complete or no advertisement was shown.
Source:

storeHighScore(level_name, level_version, score, uid, data, score_string)

Stores a high score of the current user on the AirConsole servers. High Scores are public, not secure and anyone can request and tamper with them. Do not store sensitive data. Only updates the high score if it was a higher or same score. Calls onHighScoreStored when the request is done. We highly recommend to read the High Score guide (developers.airconsole.com)
Parameters:
Name Type Description
level_name String The name of the level the user was playing. This should be a human readable string because it appears in the high score sharing image. You can also just pass an empty string.
level_version String The version of the level the user was playing. This is for your internal use.
score number The score the user has achieved
uid String | Array.<String> | undefined The UIDs of the users that achieved the high score. Can be a single uid or an array of uids. Default is the uid of this device.
data mixed | undefined Custom high score data (e.g. can be used to implement Ghost modes or include data to verify that it is not a fake high score).
score_string String | undefined A short human readable representation of the score. (e.g. "4 points in 3s"). Defaults to "X points" where x is the score converted to an integer.
Source:

storePersistentData(key, value, uid)

Stores a key-value pair persistently on the AirConsole servers. Storage is per game. Total storage can not exceed 1 MB per game and uid. Storage is public, not secure and anyone can request and tamper with it. Do not store sensitive data.
Parameters:
Name Type Description
key String The key of the data entry.
value mixed The value of the data entry.
uid String The uid for which the data should be stored. For controllers, the default is the uid of this device. Screens must provide a valid uid.
Version:
  • 1.9.0 - uid is no longer optional for requests from the screen
Source:

vibrate(time)

Vibrates the device for a specific amount of time. Only works for controllers. Note: iOS ignores the specified time and vibrates for a pre-set amount of time.
Parameters:
Name Type Description
time Number Milliseconds to vibrate the device
Source:

Type Definitions

Config

The configuration for the AirConsole constructor.
Type:
  • object
Properties:
Name Type Attributes Description
orientation string AirConsole.ORIENTATION_PORTRAIT or AirConsole.ORIENTATION_LANDSCAPE.
synchronize_time boolean | undefined If set to true, you can call getServerTime() to get the time on the game server. Default is false.
setup_document boolean | undefined Sets up the document so nothing is selectable, zoom is fixed to 1 and scrolling is disabled (iOS 8 clients drop out of fullscreen when scrolling). Default: true
device_motion number | undefined If set, onDeviceMotion gets called every "device_motion" milliseconds with data from the accelerometer and the gyroscope. Only for controllers.
translation boolean If an AirConsole translation file should be loaded.
silence_inactive_players boolean <optional>
 If set, newly joining devices will be prompted to wait while an active game is going on.
To start a game round, call setActivePlayers(X) with X larger than 0 eg 1,2,3,...
To finish a game round, call setActivePlayers(0).
Default: true, unless the game uses the automatically upgrading API version.
See Player Silencing Guide for details.
Added in 1.9.0
Source:

DeviceState

DeviceState contains information about a device in this session. Use the helper methods getUID, getNickname, getProfilePicture and getCustomDeviceState to access this data.
Type:
  • object
Properties:
Name Type Description
uid string The globally unique ID of the user.
custom string | undefined Custom device data that this API can set.
nickname string | undefined The nickname of the user.
slow_connection boolean | undefined If the user has a high server latency.
environment AirConsoleScreenEnvironment The games multiplayer environment to let multiple games in the same location play together. Only present for the screen device.
Source:

HighScore

HighScore contains information about a users high score We highly recommend to read the High Score guide (developers.airconsole.com)
Type:
  • object
Properties:
Name Type Description
level_name String The name of the level the user was playing
level_version String The version of the level the user was playing
score number The score the user has achieved
score_string String A human readable version of score.
ranks Object A dictionary of rank type to actual rank.
data mixed Custom High Score data. Can be used to implement Ghost modes or to verify that it is not a fake high score.
uids String The unique ID of the users that achieved the high score.
timestamp number The timestamp of the high score
nicknames String The nicknames of the users
relationship String How the user relates to the current user - "requested" (a user which was requested) - "airconsole" (played AirConsole together) - "facebook" (a facebook friend) - "other" (about same skill level)
location_country_code String The iso3166 country code
location_country_name String The name of the country
location_region_code String The iso3166 region code
location_region_name String The name of the region
location_city_name String The name of the city
share_url String The URL that should be used to share this high score.
share_image String The URL to an image that displays this high score.
Source: