Name	Description	Default
propertyName*	This is a short description summary	defaultValue
propertyName*	This is a short description summary	defaultValue
propertyName*	This is a short description summary	defaultValue

Article

Getting Started

Some basic setup is required before you begin to use MusicKit on the Web.

Overview

MusicKit on the Web uses JSON Web Tokens (JWTs) to interact with the Apple Music API. You must have a signed developer token in order to initialize MusicKit on the Web.

Embedding MusicKit on the Web in Your Webpage

Use the script tags and link to Apple’s hosted version of MusicKit on the Web:


<script src="https://js-cdn.music.apple.com/musickit/v3/musickit.js" data-web-components async></script>

In the example above, there are two optional attributes.

The data-web-components attribute instructs MusicKit to also load the Web Components, making them available for your application to very quickly add playback controls. If you are only making requests for data, and not supporting playback, then you would not necessarily need to include the Web Components.

The async attribute is a web standard for the <script> tag which instructs the browser to not block rendering of the page based on the loading of the JavaScript file in the src attribute. This is recommended, as MusicKit on the Web itself is initialized asynchronously; see the musickitloaded event documentation below.

Configuring MusicKit on the Web

You can configure MusicKit on the Web with a default markup setup to quickly get you started with the library, or with JavaScript to give you more control over the customization of your player. To configure the library using only markup, use the following meta tags:


<head>
  ...
  <meta name="apple-music-developer-token" content="DEVELOPER-TOKEN" />
  <meta name="apple-music-app-name" content="My Cool Web App" />
  <meta name="apple-music-app-build" content="1978.4.1" />
  ...
</head>

Configuring the library with JavaScript:


document.addEventListener('musickitloaded', async function () {
  // Call configure() to configure an instance of MusicKit on the Web.
  try {
    await MusicKit.configure({
      developerToken: 'DEVELOPER-TOKEN',
      app: {
        name: 'My Cool Web App',
        build: '1978.4.1',
      },
    });
  } catch (err) {
    // Handle configuration error
  }

  // MusicKit instance is available
  const music = MusicKit.getInstance();
});

If using the meta tags to configure MusicKit, you would not need to make a MusicKit.configure(...) call. However, you still need to wait for the musickitloaded event before you can access the MusicKit global or configured instance.

The `musickitloaded` event

MusicKit on the web is initialized asynchronously, which means the MusicKit global is not available immediately after the JavaScript file is evaluated. Instead a musickitloaded event is fired on the document when the MusicKit global is available.

Here is an example of how to listen for the musickitloaded event on the document:


document.addEventListener('musickitloaded', async function () {
  // MusicKit global is now defined.
});