Özel Web Alıcınıza Temel Özellikler Ekleme

Bu sayfada kod snippet'leri ve bir Özel Web Alıcısı uygulaması için kullanılabilen özelliklerin açıklamaları yer almaktadır.

Not: Aşağıdakileri denemenizi öneririz:

• Yayın Web Alıcısı codelab eğitimi - Google Cast SDK'sını kullanarak video yayını alabilen Cast uyumlu bir Web Alıcı uygulaması oluşturmayı adım adım öğrenin.
• CastGetr örnek uygulaması (GitHub) - Kullanıcı Deneyimi Kuralları ve Tasarım Kontrol Listesi ile uyumlu olan bu referans uygulama uygulamasını çalıştırın, görüntüleyin ve görüntüleyin.

1. Web Alıcısı ile sağlanan yerleşik oynatıcı kullanıcı arayüzünü temsil eden cast-media-player öğesi.
2. background-image, splash-image ve font-family gibi çeşitli kullanıcı arayüzü öğelerini biçimlendirmek için cast-media-player öğesine yönelik CSS benzeri özel stil.
3. Web Alıcısı çerçevesini yükleyecek bir komut dosyası öğesi.
4. İletilere müdahale etmek ve etkinlikleri işlemek için kullanılan JavaScript kodu.
5. Otomatik oynatma sırası.
6. Oynatmayı yapılandırma seçenekleri.
7. Web Alıcısı bağlamını ayarlama seçenekleri.
8. Web Alıcısı uygulamasının desteklediği komutları ayarlama seçenekleri.
9. Web Alıcısı uygulamasını başlatmak için bir JavaScript çağrısı.

Not: Oynatıcının tüm kullanıcı arayüzü durumuyla ve stiliyle birlikte çalıştığı için cast-media-player HTML öğesinin kesinlikle kullanılması önerilir.

Uygulama yapılandırması ve seçenekleri

CastReceiverContext, geliştiriciye verilen en harici sınıftır ve temel kitaplıkların yüklenmesini yönetir ve Web Alıcı SDK'sının ilk kullanıma hazırlanmasını yönetir.

Web Receiver API, bir gönderenin bağlantısının kesildiğini algılarsa SENDER_DISCONNECTED etkinliğini artırır. Web Alıcı, maxInactivity saniye olarak tanımladığımız gönderenle iletişim kuramazsa SENDER_DISCONNECTED etkinliğini de yükseltir. Geliştirme sırasında maxInactivity değerini yüksek bir değere ayarlamak iyi bir fikirdir. Böylece, Chrome Alıcısı Hata Ayıklayıcısı ile uygulamada hata ayıklarken Web Alıcısı uygulaması kapanmaz:

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; //Development only
context.start(options);

Bununla birlikte, yayınlanmış bir Web Alıcı uygulaması için maxInactivity ayarlamamak ve bunun yerine varsayılan değeri kullanmak daha iyidir. Web Alıcısı seçeneklerinin uygulamada yalnızca bir kez ayarlandığını unutmayın.

Diğer yapılandırma cast.framework.PlaybackConfig şeklindedir. Bu, aşağıdaki şekilde ayarlanabilir:

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

Bu yapılandırma, her içerik oynatmayı etkiler ve esasen geçersiz kılma davranışı sağlar. Geliştiricilerin geçersiz kılabileceği davranışların listesi için cast.framework.PlaybackConfig tanımını inceleyin. İçerikler arasındaki yapılandırmayı değiştirmek için PlayerManager kullanılarak mevcut playbackConfig öğesi alınabilir, bir geçersiz kılma değiştirilebilir, ek olarak playbackConfig sıfırlanabilir:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

PlaybackConfig geçersiz kılınmadığı takdirde getPlaybackConfig() boş bir nesne döndürür. PlaybackConfig that üzerindeki tüm tesisler undefined ise varsayılan değerleri kullanır.

Etkinlik işleyici

Web Alıcı SDK'sı, Web Alıcı uygulamanızın oynatıcı etkinliklerini işleyebilmesini sağlar. Etkinlik işleyici, işleyiciyi tetiklemesi gereken etkinlikleri belirten bir cast.framework.events.EventType parametresi (veya bu parametreler dizisi) alır. Hata ayıklama için yararlı olan önceden yapılandırılmış cast.framework.events.EventType dizileri cast.framework.events.category içinde bulunabilir. Etkinlik parametresi, etkinlik hakkında ek bilgiler sağlar.

Örneğin, bir mediaStatus değişikliğinin ne zaman yayınlandığını öğrenmek istiyorsanız etkinliği yönetmek için aşağıdaki mantığı kullanabilirsiniz:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

Not: Web Alıcısı çerçevesi, bir gönderen bu modülle bağlantı kurduğunda veya bu bağlantının bağlantısını kestiğinde otomatik olarak izlenir ve kendi Web Alıcı mantığınızda açık bir SENDER_DISCONNECTED etkinlik işleyici gerektirmez.

İleti müdahalesi

Web Alıcı SDK'sı, Web Alıcı uygulamanızın mesajlara müdahale etmesine ve bu mesajlarda özel kod yürütmesine olanak tanır. Mesaj müdahalecisi, ne tür bir mesajın müdahale edilmesi gerektiğini belirten bir cast.framework.messages.MessageType parametresi alır.

Arayanın, değiştirilen isteği veya değiştirilen istek değeriyle çözümlenen bir söz verme döndürmelidir. null işlevinin döndürülmesi, varsayılan mesaj işleyicinin çağrılmasını engeller. Daha fazla ayrıntı için Medya yükleme bölümüne bakın.

Örneğin, yükleme isteği verilerini değiştirmek istiyorsanız bu verilere müdahale etmek ve değişiklik yapmak için aşağıdaki mantığı kullanabilirsiniz:

Dikkat: LOAD müdahalecide LoadRequestData öğesinin queueData özelliğini eklemeyin veya değiştirmeyin. queueData zaten okunup sıraya uygulandığından bu işlem, oynatma işlemini etkilemez. Daha fazla bilgi için sıralı rehbere bakın.

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

Hata işleme

Mesaj müdahalecide hata oluştuğunda Web Alıcı uygulamanızın uygun bir cast.framework.messages.ErrorType ve cast.framework.messages.ErrorReason kodu döndürmesi gerekir.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

Mesaj müdahalesi ve etkinlik işleyici

Mesaj müdahalesi ve etkinlik işleyici arasındaki bazı önemli farklar şunlardır:

• Etkinlik işleyici, istek verilerini değiştirmenize izin vermez.
• Etkinlik dinleyici, en iyi analizi veya özel bir işlevi tetiklemek için en iyi seçenektir.

Not: Etkinlik dinleyicisi, CORE, DEBUG veya FINE enum'u kullanarak etkinlik çatısını dinlemek için de kullanılabilir.

playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });

• Mesaj müdahalesi sayesinde bir mesajı dinleyebilir, müdahale edebilir ve istek verilerini değiştirebilirsiniz.
• Mesaj müdahalesi, istek verileriyle ilgili özel mantığı yönetmek için en iyi şekilde kullanılır.

Medya yükleniyor

MediaInformation, cast.framework.messages.MessageType.LOAD mesajında medya yükleme için entity, contentUrl ve contentId dahil çok sayıda özellik sağlar.

entity, hem gönderen hem de alıcı uygulamalarınızda uygulamanızda kullanmanız önerilen özelliktir. Özellik, oynatma listesi veya belirli bir medya içeriği olabilen bir derin bağlantı URL'sidir.

contentUrl, oynatılabilir bir URL için tasarlanmıştır ve kullanılabilir olduğunda kullanılabilir.

Değerin medya URL'si, gerçek bir kimlik veya özel arama için bir anahtar parametresi olup olmadığından emin olunmaması nedeniyle contentId kullanımdan kaldırıldı.

Gerçek kimliği veya anahtar parametrelerini depolamak için entity, medya URL'si için contentUrl kullanmanız önerilir. entity snippet'inin LOAD isteğinde mevcut olduğu ve oynatılabilir contentUrl değerinin alındığı aşağıdaki snippet'te bir örnek gösterilmektedir:

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      ...

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

Cihaz özellikleri

getDeviceCapabilities yöntemi, bağlı Cast cihazı ve buna bağlı video ya da ses cihazı hakkında cihaz bilgileri sağlar. getDeviceCapabilities yöntemi, Google Asistan, Bluetooth ve bağlı ekran ile ses cihazları için destek bilgileri sağlar.

Bu yöntem, enum için cihaz özelliğini almak üzere belirtilen enum'lardan birini ileterek sorgulayabileceğiniz bir nesne döndürür. Sıralamalar, cast.framework.system.DeviceCapabilities içinde tanımlanır.

Bu örnekte, Web Alıcı cihazının sırasıyla IS_HDR_SUPPORTED ve IS_DV_SUPPORTED tuşlarıyla HDR ve DolbyVision (DV) oynatma özelliğine sahip olup olmadığı kontrol edilmektedir.

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

Kullanıcı etkileşimini işleme

Kullanıcı, gönderen uygulamaları (Web, Android ve iOS), Asistan özellikli cihazlarda sesli komutlar, akıllı ekranlarda dokunmatik kontroller ve Android TV cihazlarında uzaktan kumanda aracılığıyla Web Alıcı uygulamanızla etkileşim kurabilir. Cast SDK'sı, Web Alıcı uygulamasının bu etkileşimleri işlemesi, uygulama kullanıcı arayüzünü kullanıcı işlemi durumları aracılığıyla güncellemesi ve isteğe bağlı olarak herhangi bir arka uç hizmetini güncellemek için değişiklikleri göndermesi için çeşitli API'ler sağlar.

Desteklenen medya komutları

Kullanıcı arayüzü kontrol durumları, iOS ve Android gönderenleri için genişletilmiş kumandalar, dokunmatik cihazlarda çalışan alıcı ve uzaktan kumanda uygulamaları ve Android TV cihazlarındaki alıcı uygulamaları için MediaStatus.supportedMediaCommands tarafından desteklenir. Özellikte belirli bir bit tabanlı Command etkinleştirildiğinde bu işlemle ilgili düğmeler etkinleştirilir. Değer ayarlanmazsa düğme devre dışı bırakılır. Bu değerler Web Alıcısı'nda şu yöntemlerle değiştirilebilir:

1. Belirli bir Commands ayarlamak için PlayerManager.setSupportedMediaCommands özelliğini
2. addSupportedMediaCommands kullanarak yeni bir komut ekleme
3. removeSupportedMediaCommands kullanarak mevcut bir komutu kaldırma.

playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

Alıcı, güncellenen MediaStatus dosyasını hazırladığında değişiklikleri supportedMediaCommands özelliğine ekler. Durum yayınlandığında, bağlı gönderen uygulamaları kullanıcı arayüzündeki düğmeleri uygun şekilde günceller.

Not: supportedMediaCommands ürününde değişiklik yapıldığında, gösterilen düğme türü değişmez. Bunlar, doğrudan gönderenin (iOS, Android) ve Controls alıcının API'sinde ayarlanır. Bu değişiklikleri desteklemek için supportedMediaCommands kullanan tek istisna, akıllı ekran cihazlarının ana ekranındaki medya oynatma kartlarıdır.

Desteklenen medya komutları ve dokunmatik cihazlar hakkında daha fazla bilgi için Accessing UI controls kılavuzuna bakın.

Kullanıcı işlemi durumlarını yönetme

Kullanıcılar kullanıcı arayüzüyle etkileşimde bulunduklarında veya sesli komutlar gönderdiğinde, oynatılan öğeyle ilgili içeriğin ve özelliklerin oynatılmasını kontrol edebilirler. Oynatmayı kontrol eden istekler SDK tarafından otomatik olarak işlenir. Oynatılan geçerli öğenin özelliklerini (ör. LIKE komutu) değiştiren istekler, alıcı uygulamanın bunları işlemesini gerektirir. SDK, bu tür istekleri işlemek için bir dizi API sağlar. Bu istekleri desteklemek için aşağıdakileri yapmanız gerekir:

• USER_ACTION iletiye müdahale edin ve istenen işlemi belirleyin.
• Kullanıcı arayüzünü güncellemek için MediaInformation UserActionState alanını güncelleyin.

Not: Gerekirse kullanıcının tercihini korumak için işlemi ilgili arka uçlara POST yapabilirsiniz.

Aşağıdaki snippet, USER_ACTION mesajına müdahale edip istenen değişiklikle arka ucu çağırmayı işler. Daha sonra, alıcıdaki UserActionState'nin güncellenmesi için bir çağrı oluşturur.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

Aşağıdaki snippet, bir arka uç hizmetine çağrıyı simüle eder. İşlev, kullanıcının istediği değişiklik türünü görmek için UserActionRequestData öğesini kontrol eder ve yalnızca işlem arka uç tarafından destekleniyorsa ağ çağrısı yapar.

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

Aşağıdaki snippet, UserActionRequestData öğesini alır ve MediaInformation etiketinden UserActionState anahtar kelimesini ekler veya kaldırır. MediaInformation öğesinin UserActionState öğesinin güncellenmesi, istenen işlemle ilişkili düğmenin durumunu değiştirir. Bu değişiklik; akıllı ekran kontrolleri kullanıcı arayüzü, uzaktan kumanda uygulaması ve Android TV kullanıcı arayüzüne yansıtılır. Ayrıca, iOS ve Android gönderenler için genişletilmiş kumandanın kullanıcı arayüzünü güncellemek amacıyla giden MediaStatus mesajlarıyla da yayınlanır.

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

Sesli komutlar

Aşağıdaki medya komutları, şu anda Asistan özellikli cihazlar için Web Alıcı SDK'sında desteklenmektedir. Bu komutların varsayılan uygulamaları cast.framework.PlayerManager bölümünde bulunur.

Komut	Açıklama
Çal	Oynatmayı duraklat veya devam ettir.
Duraklat	Şu anda oynatılan içeriği duraklatın.
Önceki	Medya sıranızdaki önceki medya öğesine atlayın.
Sonraki	Medya sıranızdaki bir sonraki medya öğesine atlayın.
Durdur	Şu anda oynatılan medyayı durdur.
Yok Tekrarlama	Sıradaki son öğenin oynatılması bittiğinde, sıradaki medya öğelerinin tekrarlanmasını devre dışı bırak.
Yinelenen Tekli	Şu anda oynatılan medyayı süresiz olarak tekrar et.
Tümünü Tekrarla	Sıradaki son öğe oynatıldığında, sıradaki tüm öğeleri tekrarlayın.
Tümünü Tekrarla ve Karıştır	Sıradaki son öğenin oynatılması tamamlandıktan sonra sırayı karıştırıp sıradaki tüm öğeleri tekrarlayın.
Karışık çal	Medya sıranızdaki medya öğelerini karıştırın. Not: LOAD mesajının loadRequestData içinde ayarlanmışsa oynatmadan önce shuffle işaretini kullanarak da medyayı karıştırabilirsiniz.
Altyazılar AÇIK / KAPALI	Medyanız için Altyazıyı Etkinleştirin / Devre Dışı Bırakın. Etkinleştir / Devre dışı bırak dillerine göre de kullanılabilir.
Mutlaka ara	Belirtilen mutlak zamana atlar.
Geçerli zamana göre arama	Geçerli oynatma süresine göre belirtilen zaman aralığında atlar veya geri atlar.
Tekrar Oyna	Şu anda oynatılan medyayı yeniden başlatın veya en son oynatılan medya öğesini oynatın.
Oynatma hızını ayarlama	Değişken medya oynatma hızı. Bu sorun, varsayılan olarak ele alınmalıdır. Gelen ücret isteklerini geçersiz kılmak için SET_PLAYBACK_RATE mesaj alıcısını kullanabilirsiniz.

Sesli desteklenen medya komutları

Sesli komutların Asistan özellikli bir cihazda medya komutu tetiklemesini önlemek için önce desteklemeyi planladığınız desteklenen medya komutlarını ayarlamanız gerekir. Daha sonra CastReceiverOptions.enforceSupportedCommands özelliğini etkinleştirerek bu komutları zorunlu kılmanız gerekir. Cast SDK'sı gönderenlerdeki ve dokunmatik özellikli cihazlardaki kullanıcı arayüzü, bu yapılandırmaları yansıtacak şekilde değişecektir. Bayrak etkin değilse gelen sesli komutlar yürütülür.

Örneğin, gönderen uygulamalarınızdan ve dokunmatik özellikli cihazlarınızdan PAUSE özelliğine izin verirseniz alıcınızı da bu ayarları yansıtacak şekilde yapılandırmanız gerekir. Yapılandırıldığında, desteklenen komutlar listesine dahil edilmezse gelen tüm sesli komutlar atlanır.

Aşağıdaki örnekte CastReceiverContext öğesini başlatırken CastReceiverOptions öğesini sağlıyoruz. PAUSE komutu için destek eklendi ve oynatıcının yalnızca bu komutu desteklemesi zorunlu kılındı. Sesli komut, SEEK gibi başka bir işlem için istekte bulunursa reddedilir. Kullanıcıya komutun henüz desteklenmediği bildirilir.

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

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

Kısıtlamak istediğiniz her komut için ayrı bir mantık uygulayabilirsiniz. enforceSupportedCommands işaretini kaldırın. Kısıtlamak istediğiniz her komut için gelen mesaja müdahale edebilirsiniz. Burada, Asistan özellikli cihazlara verilen SEEK komutlarının Web Alıcısı uygulamanızda bir arama tetiklememesi için SDK tarafından sağlanan isteğe müdahale edebiliriz.

Uygulamanızın desteklemediği medya komutları için NOT_SUPPORTED gibi uygun bir hata nedeni döndürün.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

Ses etkinliğinden arka plan oluşturma

Cast platformu, kullanıcının konuşmasını dinleme veya konuşma gibi Asistan etkinlikleri nedeniyle uygulamanızın sesini arka plana geçirirse etkinlik başladığında Web Alıcısı uygulamasına NOT_IN_FOCUS FocusState mesajı gönderilir. Etkinlik sona erdiğinde IN_FOCUS ile başka bir mesaj gönderilir. Uygulamanıza ve oynatılan medyaya bağlı olarak, FocusState NOT_IN_FOCUS ise medya türünü FOCUS_STATE mesaj türüne müdahale ederek duraklatabilirsiniz.

Örneğin, Asistan bir kullanıcı sorgusuna yanıt veriyorsa sesli kitap çalmayı duraklatmak iyi bir kullanıcı deneyimi sağlar.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

Sesle belirtilen altyazı dili

Kullanıcı altyazıların dilini açıkça belirtmediğinde altyazılar için kullanılan dil, komutun söylendiği dille aynı olur. Bu senaryolarda, gelen mesajın isSuggestedLanguage parametresi, ilişkili dilin kullanıcı tarafından önerilip önerilmediğini veya açıkça talep edilip edilmediğini gösterir.

Örneğin, dil, komut dosyasının konuşulduğu dile göre tahmin edildiğinden isSuggestedLanguage, "Ok Google, altyazıları aç" komutu için true olarak ayarlanır. Dil açıkça isteniyorsa (ör. "Ok Google, İngilizce altyazıları aç") isSuggestedLanguage, false olarak ayarlanır.

Meta veri ve ses yayını

Sesli komutlar varsayılan olarak Web Alıcısı tarafından işlense de içeriğinizin meta verilerinin eksiksiz ve doğru olduğundan emin olmanız gerekir. Bu, sesli komutların Asistan tarafından doğru şekilde işlenmesini ve meta verilerin, Google Home uygulaması ve Google Home Hub gibi akıllı ekranlar gibi yeni arayüz türlerinde düzgün bir şekilde gösterilmesini sağlar.

Akış aktarma

Not: Ses Web Alıcıları varsayılan olarak akış genişletmeyi destekler. Burada oturuma Cast uyumlu ek cihazlar eklenir. Video Web Alıcıları'nın, akış aktarımını desteklemek için bu bölümdeki adımları uygulaması gerekir.

Oturum durumunu korumak, kullanıcıların ses komutlarını, Google Home uygulamasını veya akıllı ekranları kullanarak mevcut ses ve video akışlarını cihazlar arasında taşıyabileceği akış aktarımının temelini oluşturur. Medya, bir cihazda (kaynak) oynamayı durdurur ve başka bir cihazda (hedef) devam eder. En son donanım yazılımına sahip tüm Yayın cihazları, akış aktarımında kaynak veya hedef işlevi görebilir.

Akış aktarımı için etkinlik akışı şöyledir:

1. Kaynak cihazda:
   1. Medyanın oynatılması durdurulur.
   2. Web Alıcısı uygulaması, mevcut medya durumunu kaydetmek için bir komut alır.
   3. Web Alıcısı uygulaması kapatıldı.
2. Hedef cihazda:
   1. Web Alıcısı uygulaması yüklendi.
   2. Web Alıcısı uygulaması, kayıtlı medya durumunu geri yüklemek için bir komut alır.
   3. Medya oynatılmaya devam ediyor.

Medya durumu öğeleri arasında şunlar bulunur:

• Şarkının, videonun veya medya öğesinin belirli bir konumu ya da zaman damgası.
• Daha geniş bir sırada (ör. oynatma listesi veya sanatçı radyosu) yer alır.
• Kimliği doğrulanmış kullanıcı.
• Oynatma durumu (örneğin, oynatılıyor veya duraklatıldı).

Akış aktarımı etkinleştiriliyor

Web Alıcınız için akış aktarımını uygulamak üzere:

1. supportedMediaCommands alanını STREAM_TRANSFER komutuyla güncelleyin:

   playerManager.addSupportedMediaCommands(
   cast.framework.messages.Command.STREAM_TRANSFER, true);

2. İsteğe bağlı olarak Oturum durumunu koruma bölümünde açıklandığı gibi SESSION_STATE ve RESUME_SESSION mesaj kesicilerini geçersiz kılın. Bunları yalnızca özel verilerin oturum anlık görüntüsünün bir parçası olarak depolanması gerekiyorsa geçersiz kılın. Aksi takdirde, oturum durumlarını korumak için varsayılan uygulama, akış aktarımını destekler.

Oturum durumunu koruma

Web Alıcı SDK'sı, mevcut medya durumunun anlık görüntüsünü alıp durumu bir yükleme isteğine dönüştürerek ve yükleme isteğini kullanarak oturumu devam ettirerek Web Alıcı uygulamalarının oturum durumlarını koruması için varsayılan bir uygulama sağlar.

Web Alıcısı tarafından oluşturulan yükleme isteği, gerekirse SESSION_STATE mesaj alıcısında geçersiz kılınabilir. Yükleme isteğine özel veriler eklemek istiyorsanız bu verileri loadRequestData.customData bölümüne yerleştirmenizi öneririz.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

Özel veriler, RESUME_SESSION mesaj alıcısındaki loadRequestData.customData bölümünden alınabilir.

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

İçerik ön yükleme

Web Alıcısı, sıradaki geçerli oynatma öğesinden sonra medya öğelerinin önceden yüklenmesini destekler.

Önceden yükleme işlemi, yaklaşan öğelerin birkaç segmentini önceden indirir. Spesifikasyon, QueueItem nesnesindeki preloadTime değerinde yapılır (sağlanmazsa varsayılan olarak 20 saniyedir). Süre, o anda oynatılan öğenin sonuna göre saniye cinsinden ifade edilir . Yalnızca pozitif değerler geçerlidir. Örneğin, değer 10 saniyeyse bu öğe, önceki öğe tamamlanmadan 10 saniye önce önceden yüklenir. Önceden yükleme süresi mevcut öğede kalan süreden yüksekse ön yükleme mümkün olan en kısa sürede gerçekleşir. Sıra Öğesinde çok büyük bir önceden yükleme değeri belirtilirse, geçerli öğeyi her oynattığımızda, bir sonraki öğeyi önceden yüklüyoruz. Ancak bu değer, mevcut oynatma öğesinin bant genişliğini ve akış performansını etkileyebileceği için bu ayarı ve geliştiriciye seçimini bırakırız.

Önceden yükleme, HLS, DASH ve Smooth akış içeriklerinde varsayılan olarak çalışır.

Yayınlama cihazları yalnızca bir medya öğesini desteklediğinden ve mevcut bir içerik öğesi oynatılmaya devam ederken önceden yüklemek için kullanılamaz. Bu nedenle, MP3 gibi normal MP4 video ve ses dosyaları önceden yüklenmez.

Özel mesajlar

Mesaj alışverişi, Web Alıcı uygulamaları için temel etkileşim yöntemidir.

Gönderen, gönderenin çalıştığı platform (Android, iOS, Web) için gönderen API'lerini kullanarak bir Web Alıcısına ileti gönderir. Etkinlik işleyicilere aktarılan etkinlik nesnesi (mesajın manifest dosyası), verilerin belirli etkinlik türünün özelliklerini aldığı bir veri öğesine (event.data) sahiptir.

Bir Web Alıcı uygulaması, belirtilen bir ad alanındaki mesajları dinlemeyi seçebilir. Bu nedenle Web Alıcı uygulamasının bu ad alanı protokolünü desteklediği söylenir. Daha sonra, söz konusu ad alanında iletişim kurmak isteyen tüm bağlı gönderenler, uygun protokolü kullanmak için karar verir.

Tüm ad alanları bir dizeyle tanımlanır ve "urn:x-cast:" ile başlamalı, ardından herhangi bir dize gelmelidir. Örneğin, "urn:x-cast:com.example.cast.mynamespace".

Not: Medya mesajı ad alanı "urn:x-cast:com.google.cast.media" ayrılmıştır. Hem gönderen hem de Web Alıcı'da Yayın API'leri kullanılarak gönderilen medya mesajları, kurala göre medya ad alanı protokolünü kullanır. Medya mesajları hakkında daha fazla bilgi için Medya ve oynatıcılar bölümünü inceleyin.

Aşağıda, web alıcısının bağlı gönderenlerden gelen özel mesajları dinlemesi için bir kod snippet'i verilmiştir:

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

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

Benzer şekilde, Web Alıcı uygulamaları, bağlı gönderenlere ileti göndererek Web Alıcısı'nın durumu hakkında bilgi verebilir. Bir Web Alıcı uygulaması, CastReceiverContext cihazında sendCustomMessage(namespace, senderId, message) kullanarak mesaj gönderebilir. Bir Web Alıcı, alınan bir iletiye yanıt olarak veya uygulama durumu değişikliği nedeniyle tek bir gönderene ileti gönderebilir. Noktalı mesajlaşmanın (64 KB sınırıyla) ötesinde, bir Web Alıcısı tüm bağlı gönderenlere de mesaj yayınlayabilir.

Ses cihazları için yayınlama

Yalnızca ses oynatma konusunda destek almak isterseniz Ses cihazları için Google Cast kılavuzuna bakın.

Android TV

Bu bölümde, Google Web Alıcısı'nın girişlerinizi, oynatma olarak ve Android TV uyumluluğu olarak nasıl kullandığı anlatılmaktadır.

Uygulamanızı uzaktan kumandayla entegre etme

Android TV cihazında çalışan Google Web Alıcısı, cihazın kontrol girişlerindeki girişi (el tipi uzak kumanda) Medya Oynatma Mesajları'nda açıklandığı gibi urn:x-cast:com.google.cast.media ad alanı için tanımlanan medya oynatma mesajları olarak çevirir. Uygulamanız, Android TV'nin kontrol girişlerinden temel oynatma kontrolüne izin vermek için uygulama medya oynatmasını kontrol etmek üzere bu mesajları desteklemelidir.

Android TV uyumluluğuyla ilgili yönergeler

Uygulamanızın Android TV ile uyumlu olduğundan emin olmak için kaçınılması gereken bazı öneriler ve yaygın hatalar aşağıda verilmiştir:

• Kullanıcı aracısı dizesinin hem "Android" hem de "CrKey" içerdiğini unutmayın. Bazı siteler "Android" etiketini tespit ettikleri için yalnızca mobil olan bir siteye yönlendirme yapabilir. Kullanıcı aracısı dizesinde "Android"in her zaman bir mobil kullanıcıyı gösterdiğini varsaymayın.
• Android'in medya yığını, verileri getirmek için şeffaf GZIP kullanabilir. Medya verilerinizin Accept-Encoding: gzip öğesine yanıt verebildiğinden emin olun.
• Android TV HTML5 medya etkinlikleri, Chromecast'ten farklı zamanlamalarda tetiklenebilir. Bu durum, Chromecast'te gizlenen sorunları ortaya çıkarabilir.
• Medyayı güncellerken timeupdate, pause ve waiting gibi <audio>/<video> öğeleri tarafından tetiklenen medya ile ilgili etkinlikleri kullanın. progress, suspend ve stalled gibi ağla alakalı etkinlikler platforma bağlı olduğundan genellikle bu etkinliklerden kaçının. Alıcınızdaki medya etkinliklerini işleme hakkında daha fazla bilgi için Medya etkinlikleri bölümüne bakın.
• Alıcı sitenizin HTTPS sertifikalarını yapılandırırken ara CA sertifikaları eklediğinizden emin olun. Doğrulama için Qualsys SSL test sayfasına göz atın: Sitenizin güvenilir sertifika yolu "ek indirme" etiketli bir CA sertifikası içeriyorsa Android tabanlı platformlarda yüklenmeyebilir.
• Chromecast, alıcı sayfasını 720p grafik düzleminde gösterirken Android TV'yi içeren diğer Cast platformları, sayfayı 1080p'ye kadar görüntüleyebilir. Alıcı sayfanızın farklı çözünürlüklerde sorunsuz şekilde ölçeklendirildiğinden emin olun.