playnetwork-sdk v1.4.12
PlayNetwork Node.js SDK
This module is an open source project with the goal of making the task of consuming various PlayNetwork APIs easy and straight-forward.
Install
npm install playnetwork-sdk
Usage
Getting Started
Music
This module can be used to interact with the Collection API, Track API, and Station API to retrieve content programming and track meta-data.
Collections
Stations
Broadcasts
Tracks
Content
This module can be used to interact with the PlayNetwork Content API to retrieve tracks, verify existence of tracks to acknowledge download.
Playback
This module can be used to interact with the Playback API to get NowPlaying information, play history and record playback.
Playerservice
This module can be used to interact with Playnetwork's socket-io service, https://player-svc.apps.playnetwork.com, to allow realtime communication to/from a device for the purposes of gathering information about that device and controling music playback
Settings
This module provides support for retrieving location / device specific environment settings, including network details, proxy configuration, throttling and more.
Location
This module allows one to retrieve information for locations as PlayNetwork understands them.
Device
This module enables simple access to device group and individual device status information.
- allDevices
- allGroups
- createDiagnostics
- createEventMessages
- createStatusReport
- getAnalytics
- getDevice
- getDevices
- getGroup
- getGroupAnalytics
- getGroupDevices
- getGroups
- getGroupsAnalytics
Getting Started
Constructor
The PlayNetwork SDK must be configured with a valid and active clientId
and secret
prior to use. If #configure
is not called, no functionality within the SDK is enabled and all SDK sub-modules (i.e. music
, settings
, content
, etc.) will be undefined
.
var playnetwork = require('playnetwork-sdk');
playnetwork.configure(
'<CLIENT_ID>',
'<CLIENT_SECRET>');
// echo configured settings
console.log(playnetwork.options());
Shared Credentials File
Alternatively, the PlayNetwork SDK may be configured with a clientId
and secret
using a shared credentials file.
By default, the SDK will search for the shared credentials file within process.env.HOME
(or process.env.USERPROFILE
when using Windows) at the following path: .playnetwork/credentials.json
(i.e. /home/ubuntu/.playnetwork/credentials.json
, etc.). A credentials file path can alternatively be specified via options when calling #configure
.
When using the shared credentials file, the file must be in the following JSON format:
{
"clientId": "<CLIENT_ID>",
"secret": "<SECRET>"
}
Example #configure
usage for loading the clientId and secret from the default credentials path:
var playnetwork = require('playnetwork-sdk');
playnetwork.configure();
Example #configure
usage for loading the clientId and secret from a specified file path:
var playnetwork = require('playnetwork-sdk');
playnetwork.configure({
key {
credentialsPath : '/path/to/credentials.json'
}
});
Options
The PlayNetwork SDK allows for a set of additional configuration parameters to be specified as an optional argument to the #configure
method. This parameter is fully optional and, by default, all communication occurs with the PlayNetwork production environment.
The supported options are as follows:
content
host
- the hostname of the content APIsecure
- defaults totrue
, defines when the API uses TLS
key
host
- the hostname of the key APIsecure
- defaults totrue
, defines when the API uses TLScacheTokens
music
collection
host
- the hostname of the collection APIsecure
- defaults totrue
, defines when the API uses TLS
station
host
- the hostname of the station APIsecure
- defaults totrue
, defines when the API uses TLS
track
host
- the hostname of the track APIsecure
- defaults totrue
, defines when the API uses TLS
playback
host
- the hostname of the playback APIsecure
- defaults totrue
, defines when the API uses TLS
player
host
- the hostname of the playerservice appsecure
- defaults totrue
, defines when the API uses TLS
provision
host
- the hostname of the provision APIsecure
- defaults totrue
, defines when the API uses TLS
settings
host
- the hostnamesecure
-
See the following example that configures the SDK for interaction with a sandbox PlayNetwork environment (_note: this is an example only).
var
playnetwork = require('playnetwork-sdk'),
options = {
content : {
host : 'sandbox-content-api.apps.playnetwork.com'
},
key : {
host : 'sandbox-key-api.apps.playnetwork.com'
},
music : {
collection : {
host : 'sandbox-collection-api.apps.playnetwork.com'
},
station : {
host : 'sandbox-station-api.apps.playnetwork.com'
},
track : {
host : 'sandbox-track-api.apps.playnetwork.com'
}
},
playback : {
host : 'sandbox-playback-api.apps.playnetwork.com'
},
player : {
host : 'https://player-svc.apps.playnetwork.com'
},
settings : {
host : 'sandbox-settings-api.apps.playnetwork.com'
}
};
playnetwork.configure(
'<CLIENT_ID>',
'<CLIENT_SECRET>',
options);
// echo configured settings
console.log(playnetwork.options());
CLI
In order to use the CLI, a Shared Credentials File must configured first. Additionally, the module should be installed globally:
npm install -g playnetwork-sdk
Usage
usage: playnetwork [-s] [-a | --api] [-c | --command] [-? | -h | --help]
-s - specify pipe mode for input stream
-a <api> - the API to use
-c <command> <args> - the command and arguments to supply
-h - help
-v - verbose
-a
(or--api
): supply any sub-module of the SDK (i.e.music
,content
,playback
, etc.)-c
(or--command
): supply any method for the specified sub-module (i.e.allStations
, etc.)-s
: required when supplying additional data (in JSON format) via a pipe-v
: will display the outbound request and inbound response details for the call to the API
Examples
Get all stations:
playnetwork -a music -c allStations
Get stations with options (notice the use of -s
in the command below):
echo '{ "count" : 1, "sort" : { "desc" : "modified" } }' | playnetwork -s -a music -c allStations
Delete a broadcast with verbose output (notice the use of -v
in the command below):
playnetwork -v -a music -c deleteBroadcast <stationId> <broadcastId>
Download a legacy asset file:
playnetwork -a content -c getLegacyAssetStream <legacy.trackToken> > ~/Downloads/file.mp2
Music Module
The music module is designed to simplify interaction with the PlayNetwork CURIOMusic API. This module supports the following methods:
#allBroadcasts
This method can be used to retrieve a paginated result set of broadcasts created for the specified station.
Usage: client.music.allBroadcasts(stationId, options, callback)
stationId
- (required) - defines the station for which broadcasts should be retrievedoptions
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
var stationId = '<STATION_ID>';
client
.music
.allBroadcasts(stationId, {
start : 0,
count : 100,
sort : {
desc : 'created'
}
}).then((result) => {
console.log(
'found %d broadcasts for station %s',
result.total,
stationId);
}).catch((err) => {
console.error(err);
});
#allCollections
This method can be used to retrieve a paginated list of collections from the API.
Usage: client.music.allCollections(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.music
.allCollections({
start : 0,
count : 100,
filters : {
mandatory : {
exact : {
'legacy.programToken' : 4550361
}
}
}
}).then((result) => {
console.log('found %d collections', result.total);
}).catch((err) => {
console.error(err);
});
#allCollectionTracks
This method can be used to retrieve a paginated set of tracks from a collection in the API.
Usage: client.music.allCollectionTracks(collectionId, options, callback)
collectionId
- (required) - defines the collection for which tracks should be retrievedoptions
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
var collectionId = '<COLLECTION_ID>';
client
.music
.allCollectionTracks(collectionId, {
start : 0,
count : 100
}).then((result) => {
console.log(
'found %d tracks from collection %s',
result.total,
collectionId);
}).catch((err) => {
console.error(err);
});
#allStations
This method can be used to retrieve a paginated result set of stations from the API.
Usage: client.music.allStations(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.music
.allStations({
start : 0,
count : 100,
filters : {
mandatory : {
contains : {
'title' : 'rock'
}
}
}
}).then((result) => {
console.log(
'found %d "rock" stations',
result.total);
}).catch((err) => {
console.error(err);
});
#allStationTracks
This method can be used to retrieve a paginated set of tracks from a station in the API.
Usage: client.music.allStationTracks(stationId, options, callback)
stationId
- (required) - defines the station for which tracks should be retrievedoptions
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
var stationId = '<STATION_ID>';
client
.music
.allStationTracks(stationId, {
start : 0,
count : 100
}).then((result) => {
console.log(
'found %d tracks from station %s',
result.total,
stationId);
}).catch((err) => {
console.error(err);
});
#allTracks
This method can be used to retrieve a paginated result set of tracks from the API.
Note: Due to the implementation within the API, some filter parameters are not supported.
Usage: client.music.allTracks(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.music
.allTracks({
start : 0,
count : 100
}).then((result) => {
console.log(
'found %d tracks',
result.total);
}).catch((err) => {
console.error(err);
});
#createBroadcast
This method can be used to create a new broadcast for an existing station.
Usage: client.music.createBroadcast(stationId, options, callback)
stationId
- (required) - defines the station for which the broadcast should be createdoptions
- (optional) - defines additional parameters for the broadcastbeginDate
- (optional) - the date and time at which the broadcast schedule should begin (defaults to the current date and time if not supplied)duration
- (optional) - the length, in minutes, for the playlist (defaults to 1440 which is 24 hours)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- the response from the API
var stationId = '<STATION_ID>';
client
.music
.createBroadcast(stationId)
.then((broadcast) => {
console.log(
'successfully created broadcast with id %s',
broadcast.broadcastId);
})
.catch((err) => {
console.error(err);
});
#deleteBroadcast
This method can be used to delete an existing broadcast schedule from within a station.
Usage: client.music.deleteBroadcast(stationId, broadcastId, callback)
stationId
- (required) - defines the station within which the broadcast existsbroadcastId
- (required) - defines the broadcast to deletecallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an error
var
stationId = '<STATION_ID>',
broadcastId = '<BROADCAST_ID>';
client
.music
.deleteBroadcast(stationId, broadcastId)
.then((playlist) => {
console.log(
'successfully deleted broadcast with id %s',
broadcastId);
})
.catch((err) => {
console.error(err);
});
#getBroadcast
To retrieve a specific broadcast for a station, by broadcast identifier, use this method.
Usage: client.music.getBroadcast(stationId, broadcastId, callback)
stationId
- (required) - defines the station from which the broadcast should be retrievedbroadcastId
- (required) - defines the broadcast to retrievecallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorbroadcast
- the broadcast
var
stationId = '<STATION_ID>',
broadcastId = '<BROADCAST_ID>';
client
.music
.getBroadcast(stationId, broadcastId)
.then((broadcast) => {
console.log(
'successfully retrieved broadcast %s',
broadcast.broadcastId);
})
.catch((err) => {
console.error(err);
});
#getCollection
To retrieve a specific collection by collection identifier, use this method.
Usage: client.music.getCollection(collectionId, callback)
collectionId
- (required) - defines the collection that should be retrievedcallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorcollection
- the collection
var collectionId = '<COLLECTION_ID>';
client
.music
.getCollection(collectionId)
.then((collection) => {
console.log(
'successfully retrieved collection %s',
collection.collectionId);
})
.catch((err) => {
console.error(err);
});
#getStation
This method provides the ability to retrieve a station by identifier.
Usage: client.music.getStation(stationId, callback)
stationId
- (required) - defines the station that should be retrievedcallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorstation
- the station
var stationId = '<STATION_ID>';
client
.music
.getStation(stationId)
.then((station) => {
console.log(
'successfully retrieved station %s',
station.stationId);
})
.catch((err) => {
console.error(err);
});
#getTrack
This method provides the ability to retrieve a single track by identifier.
Usage: client.music.getTrack(alias, callback)
alias
- (required) - defines the track that should be retrieved- can be the
trackId
for the track - can be
isrc:QMRSZ1401150
where theQMRSZ1401150
refers to the ISRC - can be
appleId:1234
- can be the
callback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errortrack
- the track
var trackAlias = '<ALIAS>';
client
.music
.getTrack(trackAlias)
.then((track) => {
console.log(
'successfully retrieved track %s',
track.assetId);
})
.catch((err) => {
console.error(err);
});
#getTracks
This method allows for the lookup of multiple tracks by a specific alias. This specific functionality comes in handy when attempting to perform a bulk lookup against the CURIOMusic API.
Usage: client.music.getTracks(aliasList, callback)
aliasList
- (required) - defines an array of tracks that should be retrieved- can be the
trackId
for the track - can be the
isrc
(i.e.isrc:QMRSZ1401150
) - can be the
appleId
(i.e.appleId:1234
)
- can be the
callback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errortracks
- an array of tracks found
var trackAliasList = [
'<ALIAS_1>',
'<ALIAS_2>'
];
client
.music
.getTracks(trackAliasList)
.then((tracks) => {
console.log(
'successfully retrieved %d tracks',
tracks.length);
})
.catch((err) => {
console.error(err);
});
Content Module
This module can be used to interact with the PlayNetwork Content API to retrieve tracks, verify existence of tracks to acknowledge download.
#checkAsset
This method can be used to determine if a particular asset exists on the server.
Usage: client.content.checkAsset(track, options, callback)
track
- (required) - defines the asset to retrieveoptions
- (optional) - additional parameters useful for identifying the characteristics specific to the assetbitrate
- (optional) -channels
- (optional) -format
- (optional) -
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
var
track = {
assetId : '<ASSET_ID>'
},
options = {
bitrate : 192000,
channels : 2,
format : 'ogg'
};
client
.content
.checkAsset(track, options)
.then((exists) => {
if (exists) {
console.log('asset %s exists as requested', track.assetId);
} else {
console.error('asset %s does not exist!', track.assetId);
}
})
.catch((err) => {
console.error(err);
});
#checkLegacyAsset
This method can be used to determine if a particular asset exists on the server.
Usage: client.content.checkLegacyAsset(track, options, callback)
track
- (required) - defines the asset to retrieveoptions
- (optional) - additional parameters useful for identifying the characteristics specific to the assetbitrate
- (optional) -channels
- (optional) -format
- (optional) -
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
var track = {
legacy : {
trackToken : 12345
}
};
client
.content
.checkLegacyAsset(track)
.then((exists) => {
if (exists) {
console.log('asset %s exists as requested', track.legacy.trackToken);
} else {
console.error('asset %s does not exist!', track.legacy.trackToken);
}
})
.catch((err) => {
console.error(err);
});
#getAssetStream
This method is useful for retrieving a stream of bytes for a specific asset.
Usage: client.content.getAssetStream(track, options, callback)
track
- (required) - defines the asset to retrieveoptions
- (optional) - additional parameters useful for identifying the characteristics specific to the assetbitrate
- (optional) -channels
- (optional) -format
- (optional) -
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
var track = {
assetId : '<ASSET_ID>'
};
client
.content
.getAssetStream(track)
.then((audio) => {
let size = 0;
audio.on('data', (chunk) => {
size += chunk.length;
});
audio.on('end', () => {
console.log('completed retrieval of %d bytes', size);
});
})
.catch((err) => {
console.error(err);
});
#getLegacyAssetStream
This method is useful for retrieving a legacy asset stream of bytes for a specific asset.
Usage: client.content.getLegacyAssetStream(track, options, callback)
track
- (required) - defines the asset to retrieveoptions
- (optional) - additional parameters useful for identifying the characteristics specific to the assetbitrate
- (optional) -channels
- (optional) -format
- (optional) -
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
var track = {
legacy : {
trackToken : 12345
}
};
client
.content
.getLegacyAssetStream(track)
.then((audio) => {
let size = 0;
audio.on('data', (chunk) => {
size += chunk.length;
});
audio.on('end', () => {
console.log('completed retrieval of %d bytes', size);
});
})
.catch((err) => {
console.error(err);
});
Playback Module
The playback module is designed to simplify interaction with the PlayNetwork Playback API. This module supports the following methods:
#allPlays
This method can be used to retrieve a paginated result set of plays from the API. By default, only one play (the most recent one) is returned, but eh count
parameter can be supplied via options
to retrieve more data. Only a limited amount of time is retained for playback history and, as a result, not all plays throughout the history of the device will be available.
Usage: client.playback.allPlays(key, options, callback)
key
- (required) - defines a composite key for retrieving play history for a device (i.e.deviceId:aabbcc112233
)options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of playscount
- the total number of plays to retrieve (maximum value is100
)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.playback
.allPlays({
start : 0,
count : 10
}).then((result) => {
console.log(
'found %d plays',
result.total);
}).catch((err) => {
console.error(err);
});
#recordPlay
This method can be used to record playback for a specific device or location.
Usage: client.playback.recordPlay(playbackInfo, callback)
playbackInfo
- (required) - defines the playback info that should be recordedclient
- (optional) - defines additional information about the device upon which the play occurredhost
- host details for the playbackdeviceId
- the identifier for the host playing the content
software
- software details for the playback
content
assetId
orlegacy.trackToken
- (required) - the content being played
created
- (optional) - the time at which the play began - this is defaulted to the current date and time if omitteddeviceId
orlegacy.deviceToken
- (required) - the device upon which content is being played
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
var play = {
client : {
host : {
deviceId : 'aa:bb:cc:11:22:33'
},
software : {
platform : 'Linux',
type : 'NodePlayer',
version : 'v1.0.0'
}
},
content : {
legacy : {
trackToken : 12345
}
}
};
client
.playback
.recordPlay(play)
.then((result) => {
console.log('successfully recorded play with id %s', result.playId);
})
.catch((err) => {
console.error(err);
});
Playerservice Module
This module can be used to interact with Playnetwork's socket-io service, https://player-svc.apps.playnetwork.com, to allow realtime communication to/from a device for the purposes of gathering information about that device and controling music playback. This module supports the following methods:
#connect
This method is used to connect to Playnetwork's socket-io service.
Usage: client.player.connect(socketEventSubscriber)
socketEventSubscriber
- (required) - defines an event subsciber. The subscriber should implement the events covered in the Events section discussed below.
client
.player
.connect(socketEventSubscriber);
#disconnect
This method is used to disconnect from Playnetwork's socket-io service.
Usage: client.player.disconnect
Fires disconnected event if successful If not successful, will fire error event
client
.player
.disconnect();
#emit
This method is to emit a message to Playnetwork's socket-io service.
Usage: client.player.emit(event, jsonRpcMessage)
Params:
event (an event string defined by Playnetwork's socket-io service)
jsonRpcMessage (json RPC formatted message)
client
.player
.emit('playerUp', { mac: 'b8:e8:56:37:4c:6a' });
#Events
- Event: 'connected', fired when a successful initial connection or reconnection is made to the socket-io service Params: connection object
{
"connectionAttempt" : number indicating the connection attempts (0 for initial, n for reconnect)
"isReconnect" : true | false, (true if this is a reconnection, false otherwise)
"url" : url (String, the url that the method connected to)
}
Event: 'disconnected' Fired when client disconnects from the socket-io service
Event: 'error' Fired when an error occurs Params: error object
Event: 'message' Fired when client recieves a json rpc formatted message from Playnetwork's socket-io service
Event: 'reconnecting', fired when reconnecting to the player-svc Params: connection object
{
"connectionAttempt" : attempt, (attempt number)
"url" : url (url attempting to connect to)
};
Settings Module
The settings module is designed to simplify interaction with the PlayNetwork Settings API. This module supports the following methods:
#allSettings
This method differs slightly from all other methods with a similar name. Specifically, this method will return the settings that are assigned directly to the clientId
used to instantiate this SDK.
Usage: client.settings.allSettings(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionscallback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorsettings
- the settings
client
.settings
.allSettings()
.then((settings) => {
console.log(
'found settings with settingsId %s',
settings.settingsId);
}).catch((err) => {
console.error(err);
});
#getSettings
In order to retrieve settings for a specific device or location, this method can be used.
Usage: client.settings.getSettings(options, callback)
alias
- (required) - defines the specific settings to retrieve- can be the
settingsId
that defines a specific result - can be defined as
deviceToken:12345
where12345
is thelegacy.deviceToken
of the target settings
- can be the
options
- (optional) - can be used to supply additional filters and sorting instructionscallback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorsettings
- the settings
client
.settings
.getSettings('deviceToken:12345')
.then((settings) => {
console.log(
'found settings for device 12345 and the settingsId is %s',
settings.settingsId);
}).catch((err) => {
console.error(err);
});
Location Module
The location module is designed to simplify interaction with the PlayNetwork Location API. This module supports the following methods:
#allAccountLocations
This method can be used to retrieve a list of accounts aggregated locations from the API.
Usage: client.location.allAccountLocations(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.location
.allAccountLocations({
count : 100,
start : 0
})
.then((result) => {
console.log('successfully found %d accounts', result.total);
})
.catch((err) => {
console.error(err);
});
#allLocations
This method can be used to retrieve a list of locations from the API.
Usage: client.location.allLocations(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.location
.allLocations({
count : 100,
start : 0
})
.then((result) => {
console.log('successfully found %d locations', result.total);
})
.catch((err) => {
console.error(err);
});
#allPhysicalLocations
This method can be used to retrieve a list of physical locations from the API.
Usage: client.location.allPhysicalLocations(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.location
.allPhysicalLocations({
count : 100,
start : 0
})
.then((result) => {
console.log('successfully found %d physical locations', result.total);
})
.catch((err) => {
console.error(err);
});
#deletePhysicalLocation
This method can be used to delete a physicalLocation by physicalLocationId.
Usage: client.location.deletePhysicalLocation(physicalLocationId, callback)
physicalLocationId
- (required) - defined the physicalLocation that should be deletedcallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorphysicalLocation
- the physicalLocation
var physicalLocationId = '<PHYSICAL_LOCATION_ID>';
client
.location
.deletePhysicalLocation(physicalLocationId)
.then(() => {
console.log(
'successfully deleted physicalLocationId %s',
physicalLocationId);
})
.catch((err) => {
console.error(err);
});
#getLocation
To retrieve details for a particular location, use this method.
Usage: client.location.getLocation(locationId, options, callback)
locationId
- (required) - defines the location that should be retrievedoptions
- (optional) - additional optionscallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorlocation
- the location
var locationId = '<LOCATION_ID>';
client
.location
.getLocation(locationId)
.then((location) => {
console.log(
'successfully retrieved location %s',
location.locationId);
})
.catch((err) => {
console.error(err);
});
getLocations
Works similarly to getLocation, but allows for multiple locations to be provided as a bulk request.
Usage: client.location.getLocations(locationIdList, callback)
locationIdList
- (required) - an array of locationId values to lookupcallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorlocations
- the locations
var deviceIdList = ['<LOCATION_ID_1>', '<LOCATION_ID_2>', '<LOCATION_ID_3>'];
client
.location
.getLocations(locationIdList)
.then((locations) => {
console.log(
'successfully retrieved %d locations',
locations.length);
})
.catch((err) => {
console.error(err);
});
Device Module
The device module is designed to simplify interaction with the PlayNetwork Device API. This module supports the following methods:
#allDevices
This method can be used to retrieve a list of devices from the API.
Usage: client.device.allDevices(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.device
.allDevices({
count : 100,
start : 0
})
.then((result) => {
console.log('successfully found %d devices', result.total);
})
.catch((err) => {
console.error(err);
});
#allGroups
This method can be used to retrieve a list of groups from the API.
Usage: client.device.allGroups(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
client
.device
.allGroups({
count : 100,
start : 0
})
.then((result) => {
console.log('successfully found %d device groups', result.total);
})
.catch((err) => {
console.error(err);
});
#createDiagnostics
This method can be used to update the API with specific details regarding the status of the device.
Usage: client.device.createDiagnostics(deviceId, diagnostics, callback)
deviceId
- (required) - should contain the identifier of the devicediagnostics
- (required) - an object with details regarding the status and settings of the deviceTBD
- details regarding this message required
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
let
deviceId = '<DEVICE_ID>',
diagnostics = {
// requires definition
};
client
.device
.createDiagnostics(deviceId, diagnostics)
.then(() => {
console.log('diagnostics sent!');
})
.catch((err) => {
console.error(err);
});
#createEventMessages
When needing to notify the API of one or more event message for a device, this method should be used.
Usage: client.device.createEventMessages(deviceId, messages, callback)
deviceId
- (required) - should contain the identifier of the devicemessages
- (required) - may be astring
message, a single messageobject
or an array of message strings or objectslevel
- (optional) - defaults toINFO
, this the level of severity for the message (i.e.INFO
,WARN
,ERROR
,CRITICAL
)message
- (required) - if the value of the message is a string, the value is used in this fieldtimestamp
- (optional) - defaults to now, refers to the date of the event
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
let
deviceId = '<DEVICE_ID>',
trackToken = 12345;
client
.device
.createEventMessages([{
message : `track with trackToken ${trackToken} downloaded successfully`,
timestamp : new Date()
}]).then(() => {
console.log('event logged');
}).catch((err) => {
console.error(err);
});
#createStatusReport
This method can be used to update the API with specific details regarding the status of the device.
Usage: client.device.createStatusReport(deviceId, status, callback)
deviceId
- (required) - should contain the identifier of the devicestatus
- (required) - an object with details regarding the status and settings of the deviceTBD
- details regarding this message required
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an errorresult
- result set details
let
deviceId = '<DEVICE_ID>',
status = {
// requires definition
};
client
.device
.createStatusReport(deviceId, status)
.then(() => {
console.log('status sent!');
})
.catch((err) => {
console.error(err);
});
#getAnalytics
This method can be used to retrieve a set of analytics based on a query for devices.
Usage: client.device.getAnalytics(options, callback)
options
- (optional) - can be used to supply additional filters and sorting instructionsstart
- the index at which to start selection of itemscount
- the total number of items to retrieve (maximum value is100
)filters
- additional field projections along with mandatory and optional filters (see API documentation for more details)sort
- additional sorting parameters for result (see API documentation for more details)
callback
- (optional) - a function callback that accepts two argumentserr
- populated with details in the event of an erroranalytics
- the analytics for the devices found
client
.device
.getAnalytics({
filters : {
mandatory : {
exact : {
'status.software.version' : 'v1.11.1'
}
}
}
})
.then((analytics) => {
console.log(analytics);
})
.catch((err) => {
console.error(err);
});
#getDevice
To retrieve details for a particular device, use this method.
Usage: client.device.getDevice(deviceId, options, callback)
deviceId
- (required) - defines the device that should be retrievedoptions
- (optional) - additional optionscallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errordevice
- the device
var deviceId = '<DEVICE_ID>';
client
.device
.getDevice(deviceId)
.then((device) => {
console.log(
'successfully retrieved device %s',
device.deviceId);
})
.catch((err) => {
console.error(err);
});
#getDevices
Works similarly to getDevice, but allows for multiple devices to be provided as a bulk request.
Usage: client.device.getDevices(deviceIdList, callback)
deviceIdList
- (required) - an array of deviceId values to lookupcallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errordevices
- the devices
var deviceIdList = ['<DEVICE_ID_1>', '<DEVICE_ID_2>', '<DEVICE_ID_3>'];
client
.device
.getDevices(deviceIdList)
.then((devices) => {
console.log(
'successfully retrieved %d devices',
devices.length);
})
.catch((err) => {
console.error(err);
});
#getGroup
To retrieve details for a particular group of devices, use this method.
Usage: client.device.getGroup(groupId, options, callback)
groupId
- (required) - defines the group that should be retrievedoptions
- (optional) - additional optionscallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorgroup
- the group
var groupId = '<GROUP_ID>';
client
.device
.getGroup(groupId)
.then((group) => {
console.log(
'successfully retrieved group %s',
group.deviceGroupId);
})
.catch((err) => {
console.error(err);
});
#getGroupAnalytics
To retrieve summary analytics for a particular group of devices, use this method.
Usage: client.device.getGroupAnalytics(groupId, options, callback)
groupId
- (required) - defines the group that should be retrievedoptions
- (optional) - additional optionscallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an erroranalytics
- the analytics for the group of devices
var groupId = '<GROUP_ID>';
client
.device
.getGroupAnalytics(groupId)
.then((analytics) => {
console.log(analytics);
})
.catch((err) => {
console.error(err);
});
#getGroupDevices
To retrieve a paginated list of devices for a particular group, use this method.
Usage: client.device.getGroupDevices(groupId, options, callback)
groupId
- (required) - defines the group that should be retrievedoptions
- (optional) - additional optionscallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorresult
- the result set of the request
var groupId = '<GROUP_ID>';
client
.device
.getGroupAnalytics(groupId, { start : 0, count : 100 })
.then((result) => {
console.log('successfully retrieved 100 of %d devices', result.total);
})
.catch((err) => {
console.error(err);
});
#getGroups
Works similarly to getGroup, but allows for multiple groups to be provided as a bulk request.
Usage: client.device.getGroups(groupIdList, callback)
groupIdList
- (required) - an array of deviceGroupId values to lookupcallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an errorgroups
- the groups
var groupIdList = ['<GROUP_ID_1>', '<GROUP_ID_2>', '<GROUP_ID_3>'];
client
.device
.getGroups(groupIdList)
.then((groups) => {
console.log(
'successfully retrieved %d groups',
groups.length);
})
.catch((err) => {
console.error(err);
});
#getGroupsAnalytics
Works similarly to getGroupAnalytics, but allows for multiple groups to be provided as a bulk request.
Usage: client.device.getGroupsAnalytics(groupIdList, callback)
groupIdList
- (required) - an array of deviceGroupId values to lookupcallback
- (optional) - a function callback that accepts a single argumenterr
- populated with details in the event of an erroranalytics
- the analytics for the group of devices
var groupIdList = ['<GROUP_ID_1>', '<GROUP_ID_2>', '<GROUP_ID_3>'];
client
.device
.getGroupsAnalytics(groupIdList)
.then((analytics) => {
console.log(analytics);
})
.catch((err) => {
console.error(err);
});
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago