Встраивание плеера курса из Teachbase на внешний сайт

Общая информация

Одна из ключевых задач, которую решает Teachbase для наших клиентов - проведение обучения. Чтобы ученики могли удобно изучать и проходить контент, предоставленный организатором обучения, на платформе, в личном кабинете, ученика есть плеер курса. Мы запустили новую функцию, которая сделает прохождение обучения еще удобнее, доступнее и эффективнее: теперь можно встраивать плеер курса прямо на свой сайт или любой другой ресурс с помощью iframe.

Раньше, чтобы пройти курс, тест или опрос, ученикам приходилось переходить в личный кабинет на платформе Teachbase. Теперь всё стало еще проще: можно разместить плеер с обучающим контентом непосредственно на своем сайте — будь то корпоративный портал, сайт на Tilda, WordPress или любой другой платформе - с помощью iframe. Пользователи смогут проходить обучение, тестирование или опросы, не покидая внешний ресурс.

Ключевая ценность

Это решение подходит в первую очередь для тех, кому критически важно обеспечить максимально бесшовный доступ учеников к прохождению обучения.

• Удобство для пользователей. Обучение становится ближе к аудитории. Потенциальные ученики получают доступ к курсам, тестам или опросам прямо там, где они уже находятся, без необходимости переходить в LMS. Это снижает барьеры и повышает вовлеченность в обучение. Например, организуйте обучение для новых сотрудников на корпоративном портале или обучение для клиентов или партнеров прямо на промо или основном сайте.
• Гибкость интеграции. Не важно, на чем построен внешний ресурс — наш iframe-плеер легко встраивается на любую платформу, сохраняя функциональность и стиль.
• Полный контроль в LMS. Сохраняется полное управление контентом, процессом обучения и аналитикой через Teachbase. Все данные — прогресс, результаты тестов, статистика — собираются и хранятся в аккаунте, как если бы ученики проходили обучение в своем личном кабинете.

Как это работает

Демонстрационный пример

По ссылке: https://teachbase.ru/demo-player/ (opens in a new tab)

Общие шаги для встраивания плеера из Teachbase

1. Создать или выбрать курс в Teachbase, который требуется встроить.
2. Создать в Teachbase поток в выбранном курсе.
3. Получить токен (Oauth Token) в Teachbase для инициализации встроенного плеера для пользователя: Встроенный плеер запускается в контексте конкретного ученика, курса и потока - для возможности учета статистики и прогресса прохождения. Поэтому перед инициализацией встроенного плеера требуется получение Oauth Token для ученика в Teachbase:
   1. Настроить SSO в своем аккаунте в Teachbase (сквозная авторизация пользователей между вашим сайтом и Teachbase при помощи Oauth2/Open ID): https://help.teachbase.ru/managers/api-and-integrations/08 (opens in a new tab) Важный момент: в настройках SSO в Teachbase должен быть включён параметр - Логин c мобильным токеном
   2. Перед запуском встроенного плеера на внешнем сайте/ресурсе, нужно получить OAuth Token для соответствующего пользователя в Teachbase, чтобы инициализировать для него плеер нужного курса.
4. Подключить на нужном ресурсе/сайте скрипт для использования встроенного плеера курсов из Teachbase.
5. Добавить на нужной странице ресурса/сайта код для встраивания плеера нужного курса.
6. Обратиться в техподдержку, чтобы разрешить встраивание плеера на ваш сайт - прислать название домена сайта, где будет размещаться встроенный плеер.

1.Получение токена (Oauth Token) в Teachbase для инициализации встроенного плеера

Встроенный плеер запускается в контексте конкретного ученика, курса и потока - для возможности учета статистики и прогресса прохождения. Поэтому перед инициализацией встроенного плеера требуется получение Oauth Token для пользователя в Teachbase.

Если вы хотите просто и быстро протестировать возможность встраивание плеера курса на внешний ресурс/сайт, то можно получить Oauth Token для нужного тестового ученика следующим образом:

1. Перейти на сайт https://reqbin.com/ (opens in a new tab) (ReqBin.com - это бесплатный онлайн-инструмент для тестирования API, позволяющий отправлять запросы к REST и SOAP конечным точкам прямо из браузера и анализировать ответы сервера.)
2. В поле для URL запроса ввести https://go.teachbase.ru/oauth/token
3. Выбрать Body и Form (url-encoded).
4. Ввести ключи и значения по примеру:

grant_type=password
username=ваш логин в teachbase
password=ваш пароль в teachbase

5. Нажать "Send".
6. В ответ вернется JSON с Oauth Token.

Далее, переходите сразу к пункту инструкции Подключение на нужном ресурсе/сайте скрипта для использования встроенного плеера курсов из Teachbase.

Настройка SSO

В кабинете менеджера в Teachbase перейдите в раздел "Настройки" -> "API и интеграции", в списке нужен блок настроек "Настройка OAuth 2.0 / OpenID Connect для Single Sign-On".
Заполните данные для SSO-авторизации. Подробнее о настройке можно прочитать здесь.
Важный момент: в настройках SSO в Teachbase должен быть включён параметр Логин c мобильным токеном.

Перенаправление пользователя

Перенаправьте пользователя на следующий URL:

<lms_host>/auth/sso/oauth/new/?return_to=<client_callback_url>

Замените <lms_host> на хост вашей LMS (адрес Teachbase с вашим доменом/поддоменом) и <client_callback_url> на URL обратного вызова вашей платформы.

Вход через SSO

Платформа Teachbase перенаправит клиента на вход через SSO.

Получение access_key

После успешной сессии пользователь будет перенаправлен на указанный client_callback_url, и в параметре адресной строки будет ключ access_key, необходимый для получения токена.

Получение токена

Отправьте POST-запрос на <lms_host>/oauth/token для получения токена.

Пример запроса на JavaScript:

// Допустим, у нас такие переменные
const client_callback_url = "https://client.local";
const lms_host = "https://custom.teachbase.local";

// Проверяем наличие токена в local storage
const token = localStorage.getItem("teachbaseToken");

if (!token) {
  // Если токена нет, проверяем наличие access_key в параметрах URL
  const urlParams = new URLSearchParams(window.location.search);
  const accessKey = urlParams.get("access_key");

  if (accessKey) {
    // Если access_key присутствует, отправляем запрос на получение токена
    async function getToken() {
      const body = {
        password: accessKey,
        username: "token",
        grant_type: "password"
      };

      try {
        const response = await fetch(`${lms_host}/oauth/token`, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(body)
        });

        // Получение JSON-ответа
        const data = await response.json();

        // Получение токена из JSON-ответа
        const token = data.access_token;

        // Сохранение токена в local storage
        localStorage.setItem("teachbaseToken", token);
      } catch (error) {
        console.error("Ошибка при получении токена:", error);
      }
    }

    // Вызов асинхронной функции
    getToken();
  } else {
    // Если access_key отсутствует, перенаправляем пользователя на страницу входа через SSO
    window.location = `${lms_host}/auth/sso/oauth/new/?return_to=${client_callback_url}`;
  }
}

// Этот код использует метод window.history.replaceState() для изменения текущего URL, заменяя параметры запроса пустой строкой. 
window.history.replaceState({}, document.title, window.location.pathname);

После успешного выполнения этих шагов, вы получите OAuth Token, который можно использовать для запуска внешнего плеера курса на вашей платформе. Обновлять токен не требуется, так как это делает сам плеер.

Пример ответа с токеном

{
    "access_token": "xMXV3n5a_XA3-iuGGeSxhV14etJf-P3kU04CJfSlJ6",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "vQNX80-fje_D768sGAK9YOarCSa2wkysOc6UNq2s5i",
    "created_at": 1753366402,
    "resource_owner_id": 123456,
    "resource_owner_type": "User"
}

2.Добавить на страницу ресурса/сайта код для встраивания плеера нужного курса

Получить код для встраивания плеера нужного курса для страницы вашего ресурса/сайта можно в потоке по этому курсу.

1. Перейти в Teachbase на страницу просмотра статистики нужного курса и потока, который требуется встроить.
2. Нажмите на кнопку "О потоке".
3. Нажмите на кнопку "Скопировать код для встраивания курса" - скрипт для встраивания плеера для нужного курса и потока будет скопирован в буфер обмена.
4. Встаьте скопированный код для встраивания плеера курса на необходимую вам страницу на нужном ресурсе/сайте.

Техническая информация

Основные функции скрипта для встраивания плеера курса

• Подгружает необходимые ресурсы: https://assets.teachbase.ru/tb-player/tb-player-init.min.js (opens in a new tab) - для работы встраиваемого плеера.
• Встраивает iframe с плеером на страницу.
  Это необходимо для отображения плеера курса в нужном месте на вашем сайте.
• Передает начальные параметры в iframe после загрузки.
  Параметры содержат информацию для инициализации плеера - токен доступа, ID курса, язык интерфейса и т.д.
• Обрабатывает сообщения от плеера (смена локации, закрытие и т.д.). Плеер отправляет сообщения о различных событиях, которые вы можете обработать на своей стороне.

Пример кода для встраивания

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Teachbase Player</title>
    <!-- Разместите код для подключения скрипта tb-player-init.min.js в пределах тегов <head></head> -->
    <script src="https://assets.teachbase.ru/tb-player/tb-player-init.min.js"></script>
  </head>
  <body>
    <!-- Разместите контейнер (div) для вывода плеера с id="player-container" и функцию для инициализации плеера window.initTbPlayer в нужном месте страницы в пределах тегов <body></body> -->
    <div id="player-container"></div>
	<script>
		window.initTbPlayer({
			rootId: "player-container",
			host: "https://go.teachbase.ru",
			playerUrl: "/assets/player/index.html",
			lang: "ru",
			onClose: function() {
				console.log("Player was closed");
			},
			onChangeLocation: function(location) {
				console.log("Location changed to:", location);
			},
<!-- Укажите свои значения для всех перечисленных параметров для авторизационного токена пользователя в Teachbase. Подробнее в инструкции, раздел Получение токена (Oauth Token) в Teachbase для инициализации встроенного плеера: https://help.teachbase.ru/managers/api-and-integrations/12 -->
			token: {
				access_token: "id3DDepa7YgZ2udp5MgVz7YhcOjBjIF4O7p_5SHxQGA",
				token_type: "Bearer",
				expires_in: 6768,
				refresh_token: "8mN3osBBni5O12yowkLBC5oaPMPXqNmNneGj-cJfps4",
				created_at: 1753800435,
				resource_owner_id: 6535845,
				resource_owner_type: "User"
			},
<!-- Настройка параметров в routerParams влияет на то, с какого материала будет открыт плеер курса у ученика. Если null, то плеер автоматически будет открываться на первом еще не изученном учеником материале в списке всех материалов курса. Подробнее о настройках routerParams в инструкции: https://help.teachbase.ru/managers/api-and-integrations/12 -->
			routerParams: {
				type: "material",
				sectionId: 869883,
				contentId: 3520604
			},
			accountId: 22794,
			entityId: 1063278
		});
	</script>
  </body>
</html>

Описание аргументов функции для инициализации встраиваемого плеера Teachbase

initTbPlayer(options)

Главная функция для инициализации плеера Teachbase. Инициализирует iframe и настраивает передачу сообщений.

Аргументы:

Сообщения от плеера

location. Указывает на смену локации в плеере. Обрабатывается через onChangeLocation.

• Возникает при переходе между материалами курса.
• Передает объект с новыми параметрами роутинга (type, sectionId, contentId).

close. Указывает на закрытие плеера. Обрабатывается через onClose.

• Возникает при закрытии окна/вкладки с плеером или переходе на другую страницу.
• Может использоваться для сохранения прогресса или отправки статистики.