В последние годы потоковые сервисы, такие как Spotify и Apple Music, стали для многих основным источником музыки. Основным преимуществом этих потоковых сервисов является возможность отслеживать данные прослушивания и учитывать конкретные предпочтения пользователя. Это делает интеграцию с этими службами очень полезной для вашего приложения. Например, вы можете захотеть узнать о любимых жанрах пользователя, чтобы вы могли давать обоснованные рекомендации в своем собственном приложении. Обычно это влечет за собой запрос авторизации пользователя на доступ к его информации и получение токена специально для вашего приложения для доступа к информации этого пользователя. Затем вы будете использовать этот токен с API для получения информации об учетной записи службы потоковой передачи пользователя.

Хотя у Spotify есть обширная документация в Интернете, я недавно работал над интеграцией с Apple Music и обнаружил, что это чрезвычайно сложно реализовать в веб-приложении. Хотя код был несложным, документации не хватало, и я нашел много вопросов без ответов на онлайн-форумах от разработчиков, пытающихся интегрировать Apple Music.

К счастью, мне удалось выяснить, как интегрироваться с Apple Music с помощью MusicKitJS. Процесс на самом деле довольно простой, но из-за отсутствия информации в сети разобраться было сложно. Давайте начнем с того, как сделать эту интеграцию.

Создайте идентификатор MusicKit

Во-первых, вы должны создать идентификатор MusicKit для своего приложения. По сути, это просто регистрация вашего приложения для использования Apple Music API, и эта часть хорошо документирована Apple. Вы можете увидеть шаги здесь, чтобы узнать больше о том, как создать свой идентификатор.

Создайте закрытый ключ для Apple Music

Затем вам нужно будет создать закрытый ключ для доступа к Apple Music API с использованием вашего идентификатора MusicKit. Это хорошо задокументировано шагами, найденными здесь.

Создайте веб-токен JSON

Наконец, для интеграции вашего приложения с MusicKitJS вам необходимо создать JSON Web Token (JWT). Apple предоставляет несколько полезных шагов для этого по этой ссылке. По сути, вам нужно будет преобразовать свой закрытый ключ в JWT с конкретной информацией в заголовках и полезных нагрузках утверждений. Существует множество полезных библиотек, таких как pyjwt, которые упрощают этот процесс.

Скрипт здесь — полезный пример Python, чтобы увидеть, как именно это будет работать. Поскольку срок действия JWT в конечном итоге истекает, вы захотите интегрировать этот тип логики в свой бэкэнд, чтобы его можно было вызывать перед рендерингом веб-страницы, содержащей интеграцию с Apple Music. Это позволяет вашему приложению сгенерировать новый токен, если срок действия текущего истек (в отличие от ключа API, вы не можете использовать один и тот же токен в течение длительного времени).

ПРИМЕЧАНИЕ. Для Apple Music ваш токен JWT ДОЛЖЕН быть закодирован с использованием алгоритма ES256.

Встраивание MusicKit во внешний интерфейс

Теперь, когда мы создали токен для использования MusicKitJS, мы готовы встроить MusicKitJS в JavaScript нашей веб-страницы.

<script src="https://js-cdn.music.apple.com/musickit/v1/musickit.js"></script>
<script>
   document.addEventListener('musickitloaded', function() {
       // MusicKit global is now defined
       MusicKit.configure({
          developerToken: 'INSERT TOKEN HERE',
          app: {
              name: 'INSERT NAME HERE',
              build: 'INSERT NUMBER HERE'
          }
       })
       let music = MusicKit.getInstance();
       document.getElementById('login-btn').addEventListener('click', () => {
          music.authorize().then(function(token) {
              // do something with token here
              window.location.href += "?music-user-token=" + encodeURIComponent(token);
          }).catch (e => {
             console.log ('Error:' + e );
          });
       });
   });
</script>

Это часть этого процесса, которая особенно плохо документирована. Однако приведенный выше код должен помочь с интеграцией, и, как видите, на самом деле это довольно просто. Разбираем происходящее.

Во-первых, библиотека MusicKitJS загружается так же, как любая другая библиотека JS. Затем мы добавляем прослушиватель для выполнения при загрузке скрипта. Когда это происходит, мы настраиваем экземпляр MusicKit, используя токен JWT, созданный на предыдущем шаге. Вы также должны передать имя для своего приложения и номер версии (сборки). После настройки MusicKit мы сохраняем экземпляр в переменной («музыка»), которая будет использоваться позже.

В другом месте вашей веб-страницы у вас должна быть кнопка, которую пользователи могут нажать, чтобы авторизовать ваше приложение для подключения к их учетной записи Apple Music. Мы прикрепляем к этому элементу прослушиватель событий щелчка, который вызывает authorize() для экземпляра MusicKit. Это приведет к тому, что поток аутентификации Apple Music появится на экране пользователя. Пользователь авторизует доступ к своей учетной записи, после чего интерфейс JS получит токен для доступа к своей информации. На этом этапе вы можете отправить токен на свой сервер. Теперь вы сможете получить доступ к информации об учетной записи пользователя из Apple Music API.

Дополнительная информация/примечания

  1. Вся цель этой интеграции — получить информацию о пользователе из API Apple Music. Всю документацию по Apple Music API можно найти здесь.
  2. К сожалению, в MusicKitJS есть несколько очень неописательных сообщений об ошибках. Я часто сталкивался с сообщением «Ошибка: 0». В моем случае это обычно было связано с проблемами с токенами. Если вы столкнулись с этой ошибкой, убедитесь, что срок действия токена, который вы используете во внешнем интерфейсе, не истек, и ваша логика генерации токена работает правильно.
  3. Когда ваш JavaScript получает токен, специфичный для пользователя (Apple назвала его музыкальным токеном пользователя), полезным способом использования этого является передача токена в перенаправлении на другой URL-адрес/конечную точку, где вы обрабатываете подключение к учетной записи Apple Music пользователя и получения их информации. Вы заметите, что приведенный выше код делает что-то похожее на это.
  4. Со временем это может устареть, если Apple выпустит лучшую библиотеку (с большими возможностями) для веб-интеграции с Apple Music. Надеюсь, это произойдет когда-нибудь в ближайшее время!