This plugin includes the following interactions with the ` Apple Music API, via the Web API and the Apple Musickit JS library.
Server Side Workflows
Get a Developer token
Developer tokens can be valid for up to 6 months and are used in two separate places: on the client side and server side of the application. It's best practice to generate a token that expires after a relatively short amount of time on the client side (for the "Developer Token (JWT)" in the Plugins tab) since this token is not secure and could be stolen by a technically sophisticated user.
Inputs:
Apple Developer Account Team ID
Apple Developer Account Key ID
Apple Developer Account Key (file)
Number of minutes until token expiration
Element Workflows
There is an Apple Music element which must be added to the page for music playback.
Initialize the element
Before doing any of the other Element Workflows, the element must be initialized with a valid, not-expired Developer token.
Authenticating from the app
After initialized, the user must authenticate with Apple Music (log into their Apple account) in order to listen to any music. This is true even for listening to music samples.
Music playback (play, pause, skip to next song, skip to any position in queue, play next, play later)
A number of actions exist for music playback. The only inputs for these actions are a Song ID for the "Play Next" and "Play Later" actions. The song ID can be gotten from the some Data API calls included with the plugin (see below for more info).
If additional functions are needed (shuffle playback, fast-forwarding playback, adding entire albums to the queue, etc.) then contact [email protected] for more info.
Element States
The element exposes the following states:
Is Playing (for playback): true/false
Playback State (text), has a number of options (playing, stopped, paused, seeking, loading, etc.)
Authorized (true/false)
Queued Songs (IDs) (list of texts)
Queue Position (number): number of the current song in the queue (after a song plays, it remains in the queue)
Now playing (song ID) (text)
Current Playback Time (number): seconds since start of current song
Current Playback Time Remaining (number): seconds until end of current song
Storefront (text): a 2-character code for the country where the user is located. used in the search data API call
Music User Token (text): Not currently used, User's token (for user-specific API requests, like checking their library's content)
Please note that the queue will not erase items once they are played, but instead will automatically move onto the next item in the queue.
Data Workflows
Searching for music in Apple Music's catalog
The "Search Catalog" data API will return a list of songs, artists, albums, playlists (and potentially other types? not sure if other types exist).
For the current iteration (August 4 2020) of the plugin, only song IDs will be useful for audio playback, and the "types" field of this workflow should be set to "songs".
Get a song's data by ID
Send a single song's ID to this data API call in order to get data about the song.
Additional resources
For reference, the following pages were helpful in setting up the plugin: