Permissions
Widgets declare the capabilities they need in the permissions array of
manifest.json. Request only what you use.
Permissions are enforced by the host, not by the JavaScript API: a call whose permission
you haven’t declared is refused before it reaches the player, whether you make it through
NepTunes.playPause() or by posting to the message handler yourself. Each refusal is
logged, so a control that does nothing has a findable cause:
Widget <your.widget.id> lacks permission for action: increaseVolumeThe promise APIs refuse by rejecting instead: lastFm.call(), lastFm.image() and every
NepTunes.history method reject at once with the error code permissionDenied.
"permissions": ["artwork", "playbackControl"]Available permissions
| Permission | Grants |
|---|---|
artwork |
Access to album artwork via getArtworkDataURL() and track.artworkData, and, for a widget with supportsMotionArtwork, to motion artwork. |
playbackControl |
playPause(), next(), previous(). |
volumeControl |
increaseVolume(), decreaseVolume(), toggleMute(), setVolume(). |
love |
toggleLove() and toggleDislike() (Apple Music). |
ratingControl |
Star ratings: setRating(), increaseRating(), decreaseRating(), removeRating() (Apple Music only). |
shuffleRepeatControl |
toggleShuffle(), toggleRepeat(). |
playerActivation |
activatePlayer(), switchPlayer(). |
lastFm |
Last.fm through the app: NepTunes.lastFm.call() (any read-only method), lastFm.image() for Last.fm artwork, and the narrow helpers. Loving a track also needs love. |
listeningHistory |
NepTunes’ own listening history via NepTunes.history. NepTunes 4.1+; older versions refuse to install a widget that declares it. |
Capabilities vs. permissions
Permissions are what your widget asks for. Capabilities are what the current
player supports, read them from
NepTunes.capabilities. For example, Spotify
doesn’t expose star ratings, so capabilities.canRate is false even if you hold the
ratingControl permission. Check capabilities before showing controls that the active
player can’t fulfil:
if (NepTunes.capabilities.canLove) {
loveButton.hidden = false;
}