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: increaseVolume"permissions": ["artwork", "playbackControl"]Available permissions
| Permission | Grants |
|---|---|
artwork |
Access to album artwork via getArtworkDataURL() and track.artworkData. |
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 data via NepTunes.lastFm — user stats, top charts, track info. Loving a track through it also needs love. |
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;
}