Home > Article > Web Front-end > Detailed explanation of graphic code on how to use SoundCloud API in JavaScript SDK
SoundCloud has developed an API that can be used by developers. This API allows developers to obtain almost any data they want. However, the usage of this API is a bit confusing, especially for beginners, because the SoundCloud API development documentation and documentation examples at this time use different versions of the SDK (Software Development Kit).
What is the difference between SoundCloud API and SoundCloud SDK? Fundamentally speaking, the SoundCloud API is a collection of URLs that provides developers with permission to obtain data from the SoundCloud server, and the SoundCloud SDK is a library (or client) written in advance for querying the SoundCloud API. If you want to know more about this, click the following link: http://www.php.cn/
In this tutorial, we will learn how to access the SoundCloud API and how to simplify The process of using SoundCloud SDK. We'll learn how to set up the SoundCloud SDK from SoundCloud, and then go on to write JavaScript code to get SoundCloud data, play audio and more functions provided by SoundCloud.
Understanding the concepts and working methods of HTTP and API will be helpful for you to study this tutorial. If you want to know more about APIs, I recommend you take a look: An Introduction to APIs (an introduction to APIs. Link address: http://www.php.cn/). It will also be helpful to know a little bit about asynchronous JavaScript, promises, and callback functions as you follow this tutorial. We use jQuery in our code examples in this article, so if you understand the basics of jQuery, reading the code examples in this article will be less painful.
In order to start querying the SoundClound API using JavaScript, we need to download the JavaScript SDK provided by SoundClound. As mentioned at the beginning of the article, there are two different SDK versions available.
The main difference between these two versions of the SDK is the way they return data when an asynchronous request is made and sent to the SoundClound API. . The latest version of the SDK returns a Promise, while another version of the SDK needs to return a callback function as a parameter.
I noticed a problem. With the SDK version used in the document, there seems to be a problem on the SDK user login function interface of that version. This problem is that the pop-up login window will not automatically close.
Therefore, for the sake of simplicity, and because the older version of the SDK is more stable, we will use the older version of the SDK in the article examples throughout this tutorial. This version of the SDK will need to return a callback function for the client's asynchronous request.
Set up a basic HTML document
We create a basic HTML page that serves as our home page. We include the address of the SDK in the attribute src of the 3f1c4e4b6b16bbbd69b2ee476dc4f83a tag on this page, so that we can use the functions of the SDK.
<!DOCTYPE html> <html> <head> <title>Include SDK - Using SoundCloud API</title> <script src="//connect.soundcloud.com/sdk.js"></script> </head> <body></body> </html>
Note: The SDK address we include in the src of the 3f1c4e4b6b16bbbd69b2ee476dc4f83a tag in the HTML page is the SoundCloud server address. You can also download the SDK and then quote it like the following:
<script src="sdk.js"></script>
You can use the following steps to test whether the SoundCloud SDK is loaded correctly in your webpage:
Open this page with a browser (it is recommended to use Google's Chrome browser).
Open the developer console in the browser (the shortcut key to open the developer console in the Google Chrome browser is Ctrl+Shift+J).
Enter SC in the developer console and press Enter. SC is a JavaScript object created by the SDK we just included in the HTML page.
If an unknown error occurs, it means that the SoundCloud SDK is not loaded correctly. Try refreshing it and make sure the path to your SDK file (that is, the sdk.js file) is correct.
To register a SoundCloud app, all you need to do is have a SoundCloud account. If you don't have a SoundClound account yet, create one. By registering an app, the SoundCloud servers are able to authenticate our requests so that no one else can send a request on our behalf.
Note: If we are not going to use the SoundClound user login feature in our own website, we can skip this step. This will be explained in the following section.
Open the SoundClound app page. All apps we have created will be listed on this page. Make sure you are logged in to your SoundCloud account. Note: You do not need to create a separate account for this purpose. You may use the same account for your own personal purposes.
Click the Register a new application button.
Give your app a name and click the checkbox to accept the terms of SoundCloud’s Developer Policy.
点击那个大大的”注册”按钮,来完成app的注册。
在我们成功注册之后,注册页面将直接跳转到我们刚刚创建好的app设置页面。在app设置页面上,我们将看到我们的app客户端ID,这个ID将会被用来验证授权我们的请求。我们可以关掉该页面,然后现在开始回调字段了。我们之后会用到这个客户端ID的。
通过”初始化客户端”,那也就是意味着我们使客户端准备好在它和SoundCloud API之间做数据的交换。我们可以在我们之前创建的基本HTML文档里来做初始化客户端的工作,或者在一个内部js文件里来做初始化客户端的工作。
JavaScript语法是这样做的:
SC.initialize({ client_id: "CLIENT_ID", redirect_uri: "CALLBACK_URL" });
让我们分段来看它:
上面代码中的CLIENT_ID会在我们注册app的时候提供给我们。
上面代码中的CALLBACK_URL是callback.html的URL,这个callback.html是用户登录后一个HTML文件的称呼。我们很快就会创建它。
在初始化完成之后,现在我们可以准备查询SoundCloud API了。让我们看看在那之前我们可以做的一些例子。
如果我们打开浏览器的控制台并输入”SC.”,然后与SC对象有关的方法就会列出来。SC.get(uri,callback)就是其中一个方法,这个方法用来向SoundCloud API产生GET请求。
为了获得跟踪的随机列表,我们可以使用SC.get()方法,像下面这样:
SC.get("/tracks", function(response) { for (var i = 0; i < response.length; i++) { $("ul").append("<li>" + response[i].title + "</li>"); } });
上面的代码是干什么的,它是用来查询/tracks端点并且在查询完端点后返回一个回调函数的。响应数据是保存在回调响应参数里的,它是一个有着很多属性的JavaScript对象数组,title属性就是众多属性中的一个。我们可以在代码里写:console.log(response[0])来在控制台日志输出响应数据的第一个,而不用循环遍历所有的对象和对象所对应的属性。然后,我们就会知道哪些属性我们可以使用。
注意:在这个代码示例中,我们在初始化的时候并没有指定一个回调URL。这是因为我们指定不指定都不重要。不管怎样我们的代码都会执行。但是一旦我们实现了用户登录功能,这就是必须的而且很重要了,因为当你指定一个回调URL后,其他人就不可能使用我们的Client ID。
SC对象提供了其他的方法:SC.oEmbed(url,options,callback)。该方法把SoundCloud播放器嵌入我们的网站,并且允许我们播放我们选择的轨迹。
SC.oEmbed('https://soundcloud.com/username/complete-url-to-the-track', {maxheight: 200, auto_play: false}, function(res) { $("#player").html(res.html); });
我们分段来看它:
首先在该方法的第一个参数里,我们给了一个完整的我们想要播放的跟踪URL。
该方法的第二个参数是可选参数,在这个参数里,我们可以为播放器设置一些选项。
第三个参数是一个回调函数,在这个回调函数里,我们将我们页面里的(id为player)的一个元素的内容用该播放器(res.html)的HTML代码替换。
这个跟踪路径可以用来在一个网站里嵌入一首歌或者一首音乐。
为了实现用户登录功能,我们需要有一个回调URL来达到验证授权的目的。这是OAuth协议的要求。如果你想了解OAuth协议,这里有一个OAuth协议的简单解释:OAuth 2 Simplified(链接地址:http://www.php.cn/)。因此让我们在app设置里添加一个名为”callback.html”的回调URL,这个callback.html我们接下来就会创建。
OAuth协议介绍链接地址: http://www.php.cn/
在一个用户登录后,弹出式窗口会重定向到该文件。在我们的例子中,我们把该文件定义为”callback.html”,并且该文件和我们的主页(index.html)保存在相同的目录里。这个文件就是在我们的app设置里我们需要在回调字段里给定的文件。
我们需要在回调文件里使用的代码在开发文档里有提供。然而,开发文档有点过时,因此我们需要稍微调整一下来满足现在的开发需要标准。
你可以根据你个人的喜好来调整它的通知和设计,但是现在,我们使它越简单越好:
<!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <title>Connect with SoundCloud</title> </head> <body> <h4>This popup should automatically close in a few seconds</h4> <script> document.onload = function () { window.opener.setTimeout(window.opener.SC.connectCallback, 1); } </script> </body> </html>
SC.connect(callback)就是实现用户登录功能的方法。它通过打开一个弹窗式的窗口,提醒用户登录他们的SoundCloud账户。基本的使用方法如下:
SC.connect(function () { console.log("User has logged in"); });
如下是更有趣的示例:
SC.connect(function () { SC.get("/me", function (response) { console.log("Welcome" + response.username); }); });
让我们分段来看它:
在用户完成登录以后,用户登录页面将会被重定向到我们之前创建的callback.html页面。
然后随着我们阅读完callback.html里的代码,弹出式窗口会自动关闭。
在那之后,我们的回调函数将获得回调,该回调是在SC.get()方法里通过一个GET请求到”/me”端点获得的。
当GET请求完成时,上述代码的回调函数就会执行,然后在控制台会输出一条欢迎登陆的信息。
注意:请求”/me”返回的是当前登陆用户的数据。因此,在用户登录之前请求该URL将产生一个错误的信息。
一旦用户登录完成,有很多事情我们可以做。为了演示一些功能,我在GitHub上创建了一个演示站点。
让我们看看这两个文件。在index.html里,有四个重要的p元素,它们在用户完成登录后将会填满用户的数据:
<main> <p id="ui"> <h2>Welcome <span></span></h2> <img id="avatar" /> <p id="description"></p> </p> <!-- TRACKS --> <p id="tracklist"> <h3>Your Tracks:</h3> <ul></ul> </p> <!-- PLAYLISTS --> <p id="playlists"> <h3>Your Playlists:</h3> <ul></ul> </p> <p id="player"></p> </main>
第二个最重要的文件是script.js:所有的奇迹都发生在这个文件里。大部分代码我们都很熟悉,但是我们还是快速地看看:
// Initialization of SDK SC.initialize({ client_id: "21832d295e3463208d2ed0371ae08791", redirect_uri: "http://mustagheesbutt.github.io/SC_API/callback.html" });
首先初始化我们的app。注意,这次我们用redirect_uri指定了我们的callback.html页面。这个URL或者URI必须和我们在app设置里指定的一致。
// Login handler var user_perma; $("#login").click(function () { SC.connect(function () { SC.get("/me", function (me) { user_perma = me.permalink; setUI(me.username, me.avatar_url, me.description); }); if (SC.isConnected) { $("header, main").addClass("loggedIn"); } getTracks(); getPlaylists(); }); });
然后我们给标签id为login的button添加一个点击事件句柄。当该按钮被点击时,将会在点击事件代码里执行SC.connect(callback)代码,该代码执行后,将会弹出一个窗口提示用户登录。
当用户登录完成后,弹出的窗口会关闭。然后SC.connect()里的回调函数就会执行。在回调函数里,我们对”/me”端点发起一个GET请求,而”/me”端点返回当前登录用户对象。在刚才我们发起的GET请求回调里,我们在变量user_perma里存储用户的永久链接,该参数是在全局范围定义的,所以我们之后可以使用它。
setUI()方法,getTracks()方法和getPlaylists()方法的功能分别是,设置UI,列出用户的跟踪记录和列出每个用户的播放列表。这些功能在同一个文件里已经被定义了。
//找点东西播放 function play(uri) { url = "http://soundcloud.com/" + user_perma + "/" + uri; SC.oEmbed(url, {maxheight: 200}, function (resp) { $("#player").html(resp.html); }); } //当一个播放轨迹或者一个播放列表被检查时,使用’play()’函数播放 $("ul").on("click", function (e) { var title = e.target.innerHTML; if ( tracks.hasOwnProperty(title) ) { play(tracks[title]); } else if (playlists.hasOwnProperty(title)) { play("sets/" + playlists[title]); } });
当任何跟踪路径或者播放列表名被点击,play()方法就会执行,该方法会为点击的跟踪路径或者播放列表名通过SC.oEmbed()方法来在我们的页面中嵌入一个音频播放器。
我们能通过代码做很多事情,例如获取用户类型或者更新用户的信息,获取用户的头像,接下来运行代码看看SoundCloud服务器返回的信息里用户是谁和他们的爱好是什么。
如果老版本的SDK的用户登录功能可以使用,请使用老版本的SDK。因为老版本的SDK稳定,并且返回的数据使用回调函数返回。
如果老版本的用户登录功能不可用,可以使用SDK的新版本。新版本的SDK使用promises来返回数据。
通过一个简单的GET请求就能访问SoundCloud API获取到数据。
用户特有的数据可以通过”/me”端点获取,但是只有在用户使用他们的SoundCloud账户登录我们的网站的情况下才有效。
从客户端查询一个API是一个很强大的工具,因为它在复杂的后端保存了我们的信息。SDK使我们的编程生活变得简单很多。在学习了它的基础用法后,我们甚至可以编写出更加强大的和用户更加友好的web应用。点击查看一些示例(链接地址: http://www.php.cn/),并且查看官方的SoundCloud文档来学习更多关于这个强大的API的可以使用的方法。
我希望从你那里听到你用SoundCloud SDK构建的应用的信息(或者正计划构建的应用的信息)。请让我看见你们的评论!
作者介绍:
Mustaghees Butt 是一名Web开发人员和作家
Mustaghees是一名自由的Web设计师和开发者,他有时也写些文章和教程。
他的兴趣包括计算机科学(包括机器人技术,AI人工智能和网络技术)和文学艺术。
The above is the detailed content of Detailed explanation of graphic code on how to use SoundCloud API in JavaScript SDK. For more information, please follow other related articles on the PHP Chinese website!