Migrating to JavaScript SDK 3.0.0

Version 3.0.0 represents a major technical change for the SDK and is not backwards compatible with version 2.0.0. Migrating to the new version should be pretty straight forward, though.

To upgrade to the SoundCloud JavaScript SDK version 3.0.0, replace all references to:

connect.soundcloud.com/sdk-2.0.0.js

with:

connect.soundcloud.com/sdk/sdk-3.3.2.js

JavaScript Promises

All SDK methods now return Promises instead of providing a way to pass callbacks.

SC.get('/me', function (user, error) {
  if (error) {
    alert('There was an error ' + error.message);
  } else {
    alert('Hello ' + user.username);
  }
});

Now becomes:

SC.get('/me').then(function (user) {
  alert('Hello ' + user.username);
}).catch(function (error) {
  alert('There was an error ' + error.message);
});

Instead of handling the error- and the success-case in the callback, there are two different functions that will handle the cases. The then method allows you to chain several API methods together, so that you don't need to handle error cases all over the place:

SC.put('/me', {
  user: { description: 'I am using the SoundCloud API!' }
}).then(function(){
  return SC.get('/me');
}).then(function(me){
  console.log(me.description);
}).catch(function(error){
  alert('Error: ' + error.message);
});

This not only applies to HTTP methods, but also to the callbacks that you could provide to the old SC.oEmbed, SC.recordUpload, SC.recordPlay, SC.stream and SC.connect methods. They now all return promises that will be resolved with the requested information.

New Recorder

The recorder methods are no longer tied to the global SC object. We refactored the recorder to become an independent object. This means that you can no longer use the methods SC.record, SC.recordStop, SC.recordPlay and SC.recordUpload.

All those methods (and now even more) are still available on the new recorder object. Check the SDK documentation on how to use the recorder now: SC.Recorder documentation.

var recorder = new SC.Recorder();
recorder.start();

setTimeout(function(){
  recorder.stop();
  recorder.play();
}, 5000);

New Player

The SDK comes with a new, more stable player. All player methods are still the same (we only got rid of ontimedcomments). However, since we now embed the player code into the SDK, there is no need for SC.whenStreamingReady anymore. Check out the Player documentation to see all available methods and events. Also check out the new SC.stream documentation to see how to instantiate a player.

Old SDK versions

The old SDK versions will stay online but we will no longer provide support for them.

Questions?

If you have any questions about this upgrade, please feel free create an issue in our [Github repository](https://github.com/soundcloud/soundcloud-javascript).