Using AmplitudeJS Public Methods

Beginning with AmplitudeJS 3.0, we’ve really seen the need to open up most of AmplitudeJS’ functionality to be called directly. This allows the user even more control over their audio player. Maybe they want to autoplay after an advertisement? Call Amplitude.play(). Maybe you want to shuffle a playlist automatically after another method, call Amplitude.setShufflePlaylist( playlistKey ). As you can see there can be a variety of scenarios where you will need to act directly with your player outside of the scope of a user clicking or touching an element. In this tutorial, we will touch on how to use some of these public facing methods and dive in on a few common use cases for these methods.

Overview of Methods

There are a lot of public methods, pretty much for every feature of AmplitudeJS. You can find a list of them here: Documentation – AmplitudeJS. All methods are called on the Amplitude object so in order to call any of these methods it would be Amplitude.{whateverMethod()}.

We touched on the public play() method. In order to call this method, call Amplitude.play() and it will play the current song. Let’s dive into some of the methods that require a little more help.

Binding New Elements

One of the most unique public facing methods is the Amplitude.bindNewElements() method. This is used very heavily in player environments where the songs are dynamic. This method is called after the visual display is updated to bind any new AmplitudeJS elements.

For example, say you add a song to the songs array (using Amplitude.addSong({song}); of course). You then add some elements to the page to work with this song like song containers, play/pause buttons, etc. When you add these elements, AmplitudeJS isn’t bound to them. After you add the elements to the DOM, run Amplitude.bindNewElements() and all of those elements you have just added will be hooked up and AmplitudeJS will listen to the events on them. Super helpful for dynamic environments!

Another more unique method in AmplitudeJS is the Amplitude.skipTo method. There is an element that does this as well, but a few use cases outside of the element that make this method useful. For example, say you are navigating through a website (not a single page application) and you want the audio to continue where the user last left off from. Say you have a tutorial or spoken audio. When the user navigates to a new section you could start the same audio stream at a certain point using Amplitude.skipTo( seconds, songIndex, playlist = null ) . This allows you to transition to where you need to go with ease and handle a variety of different scenarios.

Set Meta Data

This is one of the newer methods in AmplitudeJS. It allows you to dynamically set the meta data of whatever song you want in the songs array. Why would you want to do this? Say you have one song and it’s a live stream (we ill go through these in a later tutorial). This live stream is very dynamic and you only enter the meta data once. You will need to change this and sync it across the player on the screen. All you have to do is pass an integer of the song index and JSON object of meta data keyed to the fields you want to update to Amplitude.setMetaData( songIndex, songMeta ). Anything in songMeta object will update on the song with the songIndex parameter. The only field that won’t update will be the url. We will use this more when we build our live player.

This just touches on a few of the public methods available in Amplitude.JS. Another more in depth tutorial is next where we set the song played percentage with AmplitudeJS: https://serversideup.net/set-song-played-percentage-amplitudejs/.

If you have any questions or need a specific method explained more thoroughly, let me know in the comments below and I will get it added!