웹 수신기로 이전

이 가이드에서는 Cast 수신기 v2 앱을 최신 웹 수신기 앱으로 이전하는 방법을 설명합니다.

새로운 Cast 애플리케이션 프레임워크(CAF) SDK(웹 수신기 v3라고도 함)는 수신기 v2 SDK의 주요 업그레이드입니다. 웹 수신기 SDK는 미디어 웹 수신기 애플리케이션 개발을 위한 간편하고 간소화된 SDK를 제공합니다.

웹 수신기는 새로운 CAF 발신자 API와 더 일관적인 API를 제공합니다. 플레이어의 전체 통합 (MPL 및 Shaka)을 제공하며 Cast 미디어 및 Google 어시스턴트 음성 명령의 전체 구현과 지원을 제공합니다. CAF SDK는 CSS를 사용하여 쉽게 스타일을 지정할 수 있는 기본 UI와 UI 구현을 간소화하는 데이터 결합 서비스를 제공합니다.

마이그레이션이 필요한 이유

Receiver v2 애플리케이션을 Web Receiver로 이전하면 플레이어를 다루는 많은 코드를 제거할 수 있으므로 애플리케이션별 비즈니스 로직을 작성하는 데 집중할 수 있습니다.

CAF는 MPL 및 Shaka 플레이어를 원활하게 통합하여 HTTP 실시간 스트리밍 (TS 및 CMAF), MPEG-DASH, 스무스 스트리밍, 미디어 요소 소스 속성에서 지원하는 유형 (MP3, MP4, Icecast 등)을 지원합니다. 전체 목록은 Google Cast에 지원되는 미디어를 참고하세요. 현재 CAF는 사용자 제공 플레이어를 지원하지 않습니다.

CAF로 이전하면 Google 어시스턴트를 통한 음성 제어 지원이 추가됩니다. 새로운 Google 어시스턴트 음성 명령은 CAF를 사용할 때 자동으로 지원됩니다.

CAF는 새로운 미디어 명령어(예: '언어별 트랙 변경' 및 '재생 속도 변경')를 지원할 뿐만 아니라 대기열 추가, 기본 제공 광고 지원, 실시간 지원도 개선합니다.

변경사항

Web Receiver API는 Android 및 iOS용 CAF 발신자가 도입한 규칙을 따르려고 하지만 v2와는 상당히 다릅니다.

웹 수신자는 노출된 모든 API에 cast.receiver 네임스페이스 대신 새 네임스페이스 cast.framework를 사용합니다. v2에서 사용된 많은 데이터 객체는 CAF에서 동일하며 cast.framework.messages 네임스페이스 아래에 노출됩니다 (대부분 cast.receiver.media 아래).

다음 v2 서비스는 해당 CAF 서비스로 대체됩니다.

  • CastReceiverManager 클래스가 전송 세션, 발신자, 커스텀 메시지 전송, 전역 시스템 이벤트를 관리하는 싱글톤인 CastReceiverContext로 대체되었습니다. CastReceiverOptions를 사용하여 전역 애플리케이션 옵션 (예: 큐, 수신기 버전, 재생 구성 등)을 컨텍스트에 제공할 수 있습니다.
  • MediaManager 클래스는 CastReceiverContext 싱글톤의 속성인 PlayerManager로 대체되고 미디어 세션, 미디어 요청, Google 어시스턴트 음성 요청(v2의 CommandAndControlManager)을 관리하고 미디어 이벤트를 실행합니다. 플레이어 구성(MPL의 cast.player.api.Host)은 PlaybackConfig에서 제공하며, 전역적으로 또는 로드 요청별로 제공할 수 있습니다.

PlayerManager는 새로운 하위 관리자 클래스도 노출합니다.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

수신자 비즈니스 로직

비즈니스 로직을 추가하기 위한 수신기 v2 노출된 이벤트 핸들러 (예: CastReceiverManager.onReady 또는 MediaManager.onLoad). CAF에서 이벤트 핸들러는 이벤트 리스너(CastReceiverContext.addEventListener) 및 메시지 인터셉터(PlayerManager.setMessageInterceptor)로 대체됩니다. 웹 수신기에는 이벤트에 여러 개의 이벤트 리스너 (리스너는 이벤트에 영향을 주지 않음)와 메시지당 하나의 인터셉터가 있을 수 있습니다. 인터셉터는 요청을 업데이트하거나 처리 (수정된 요청, 성공 메시지 또는 오류 메시지 반환)할 수 있으며 프로미스를 반환하는 비동기 핸들러일 수 있습니다.

로드 요청 인터셉터는 애플리케이션별 로직을 추가할 수 있는 가장 일반적인 위치입니다. 발신자가 보낸 로드 요청의 경우 로드 인터셉터는 콘텐츠 ID를 콘텐츠 URL로 변환할 수 있습니다. preload 또는 precache에 명시적 인터셉터가 제공되지 않은 경우 preload 및 precache 요청에도 로드 인터셉터가 호출됩니다.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

v2 맞춤설정 미디어 상태 핸들러도 미디어 상태 메시지의 메시지 가로채기로 대체됩니다. 미디어 URL에 미디어 URL을 노출하지 않으려는 웹 수신기 앱은 로드 요청의 미디어 URL을 제공하는 URL 리졸버(PlayerManager.setMediaUrlResolver)를 제공할 수 있습니다. 이 URL은 CAF에서 내부적으로 사용되며 미디어 상태로 제공되지 않습니다.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

이벤트

웹 수신기는 CastReceiverContext와 PlayerManager의 광범위한 이벤트 집합을 제공합니다. 웹 수신기 앱은 모든 이벤트에 여러 리스너를 포함할 수 있으며 여러 이벤트에 하나의 리스너를 제공할 수도 있습니다. 일부 이벤트 그룹은 cast.framework.events.category를 참고하세요.

이 이벤트는 사용자 요청, 재생 진행률, 플레이어 처리, 하위 수준 미디어 요소 이벤트를 모두 포함합니다 (CAF는 미디어 요소 자체를 노출하지 않음).

웹 수신기 앱은 조치를 취할 이벤트 리스너 (예: 로드 완료 시 텍스트 트랙 정의 추가) 또는 분석을 위해 추가할 수 있습니다.

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

맞춤 메시지 버스

CAF는 API에서 메시지 버스를 노출하지 않습니다. 대신 특정 네임스페이스 (네임스페이스당 하나)의 메시지 리스너를 추가하는 CastReceiverContext.addCustomMessageListener와 네임스페이스의 메시지를 전송하는 CastReceiverContext.sendCustomMessage를 제공합니다. 모든 네임스페이스는 웹 수신기를 시작하기 전에 (즉, CastReceiverContext.start 호출 전에) 선언해야 합니다. 네임스페이스는 메시지 리스너를 추가하여 선언하거나 CastReceiverOptions.customNamespaces에서 시작 옵션으로 제공할 수 있습니다.

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

기본 UI

CAF는 필요에 따라 재생 진행률 표시줄과 미디어 메타데이터를 표시하는 기본 웹 수신기 UI를 제공합니다. 기본 UI는 CSS와 같은 스타일로 스타일을 지정할 수 있는 맞춤 요소(<cast-media-player>)로 제공됩니다.

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

더 많은 맞춤설정을 위해 웹 수신기 앱은 자체 UI를 구현할 수 있습니다. 웹 수신기는 UI 객체를 웹 수신기 재생 상태에 바인딩하는 데 도움이 되는 cast.framework.ui.PlayerDataBinder 클래스를 제공합니다.