Jump right in and create an app with iBroadcast by following the steps below.
Click here to view it in action
Below we will go over some aspects of the sample app to understand how it works.
1. Direct user to open the OAuth authorization URL in their browser
https://oauth.ibroadcast.com/authorize
?client_id=your_client_id
&state=your_state
&response_type=code
&code_challenge=your_code_challenge
&code_challenge_method=s256
&scope=your_scopes2. Wait for the user to log in, authorize your app, and get redirected back to the Redirect URI you configured for your app.
3. Request a token from the OAuth server:
https://oauth.ibroadcast.com
POST /token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=your_authorization_code
&client_id=your_client_id
&redirect_uri=your_redirect_uri
&code_verifier=your_code_verifier4. Store the returned access_token, refresh_token, and expires_in locally to make authenticated requests to the JSON API
For detailed steps on logging in using our OAuth 2 server, click here
Now that you have an access token, you can pass it in the header of API requests to authenticate them:
Authorization: Bearer your_access_token
If your access token as expired, the JSON API will return with result = false and authenticated = false:
{
message: "...",
result: false,
authenticated: false
}When this happens, you should attempt to acquire a new access token using the saved refresh token. To do this, make a POST request to the OAuth server:
https://oauth.ibroadcast.com
POST /token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=your_refresh_token
&client_id=your_client_id
&redirect_uri=your_redirect_uriThe server will respond with a new access_token, refresh_token, and expires_in which you should store locally to authenticate subsequent requests or refresh when expired.
Make a request to the library server:
https://library.ibroadcast.com
POST /
Content-Type: application/json
Authorization: Bearer your_access_token
{
"device_name": "Fred's Phone",
"client": "myepicapp",
"version": "1.0.0",
"mode": "library"
}The library server will respond with a JSON object containing the entirety of the user's albums, artists, tracks, playlists, and tags.
The library's format is as follows:
{
"albums": {
"albumId": [
// Array of parameters
"parameter1Value",
"parameter2Value"
],
"map": {
// Map of parameterName : index
"exampleParameterName1": 0,
"exampleParameterName2": 1,
}
},
"artists": {
// Same format as albums
},
"playlists": {
// Same format as albums
},
"tracks": {
// Same format as albums
},
"trash": {
"0": [
// Array of parameters
],
"map": {
// Map of parameterName : index
}
},
"tags": {
"tagId": {
"parameter1Name": "parameter1Value",
"parameter2Name": "parameter2Value",
"parameter3Name": "parameter3Value",
"etc": "etcValue",
}
}
}To get an album's name, for example, do the following:
albumName = library.albums[albumId][library.albums.map.name];You'll notice that "tags" is the only parameter that differs in that it does not have a map and each tag is a dictionary whose parameters can be accessed directly by parameter name.
To play music, you must construct a streaming URL for a track. This URL will return an MP3 file that you can then play using a player of your choice.
If a user plays more than 10 seconds of a track, you should record a play. If a user skips a track, you should record a skip. This is done by including "history" in any request.
To show artwork, you must construct an artwork URL for a track, album, artist, playlist, etc.
The currently playing song, playback settings, and tracks in the queue are managed by the play queue server. This is a Web Socket server that allows rapid communication between all of a user's active devices, as well as an easy way to persist now playing information.
To connect to the play queue server, first request a one-time-use token from the JSON API.
POST /s/json
Content-Type: application/json
Authorization: Bearer your_access_token
{
"device_name": "Fred's Phone",
"client": "myepicapp",
"version": "1.0.0",
"mode": "playqueue_token"
}Then, pass it in the “token” query parameter when opening a web socket connection.
socket = new WebSocket("wss://queue.ibroadcast.com/ws?token=your_playqueue_token");
The play queue server supports a number of commands that your app may want to utilize.
Read more about the Play Queue
All responses contain a "result" and a "message" parameter. If "result" is false, the request errored and you should display the error message to the user and handle the error.
Example error response:
{
"result": false,
"message": "Error message here"
}
To log out, issue a token revoke request to the OAuth server:
https://oauth.ibroadcast.com
POST /revoke
Content-Type: application/x-www-form-urlencoded
refresh_token=your_refresh_token
&client_id=your_client_id