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

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

1. Web alıcısıyla birlikte sağlanan yerleşik oynatıcı kullanıcı arayüzünü temsil eden bir 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 öğesinde özel CSS benzeri stil.
3. Web alıcı çerçevesini yükleyen bir komut dosyası öğesi.
4. Mesajları durdurmak ve etkinlikleri işlemek için JavaScript kodu.
5. Otomatik oynatma için sıraya ekleme.
6. Oynatma işlemini yapılandırma seçenekleri.
7. Web alıcı bağlamını ayarlama seçenekleri.
8. Web Alıcı uygulaması tarafından desteklenen komutları ayarlama seçenekleri.
9. Web alıcı uygulamasını başlatmak için bir JavaScript çağrısı.

Uygulama yapılandırması ve seçenekleri

Uygulamayı yapılandırma

CastReceiverContext, geliştiriciye sunulan en dış sınıftır. Alttaki kitaplıkların yüklenmesini ve Web Alıcı SDK'sının başlatılmasını yönetir. SDK, uygulama geliştiricilerin CastReceiverOptions üzerinden SDK'yı yapılandırmasına olanak tanıyan API'ler sağlar. Bu yapılandırmalar, uygulama her başlatıldığında bir kez değerlendirilir ve start çağrısında isteğe bağlı parametre ayarlanırken SDK'ya aktarılır.

Aşağıdaki örnekte, gönderen bağlantısının hâlâ etkin olup olmadığını algılamayla ilgili varsayılan davranışın nasıl geçersiz kılınacağı gösterilmektedir. Web alıcısı, bir gönderenle maxInactivity saniye boyunca iletişim kuramadığında bir SENDER_DISCONNECTED etkinliği gönderilir. Aşağıdaki yapılandırma bu zaman aşımının geçersiz kılınmasını sağlar. Bu, IDLE durumundaki sıfır bağlı gönderen olmadığında Web Alıcısı uygulamasının Chrome Uzaktan Hata Ayıklama oturumunu kapatmasını önlediğinden, sorunlarla ilgili hata ayıklama işleminde faydalı olabilir.

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

Oynatıcıyı yapılandırma

Web Receiver SDK'sı, içerik yüklerken DRM bilgileri, yeniden deneme yapılandırmaları ve istek işleyicileri gibi oynatma değişkenlerini cast.framework.PlaybackConfig kullanarak yapılandırmanın bir yolunu sağlar. Bu bilgiler PlayerManager tarafından işlenir ve oyuncular oluşturulurken değerlendirilir. Web Receiver SDK'sına her yeni yükleme aktarıldığında oynatıcı oluşturulur. Oynatıcı oluşturulduktan sonra PlaybackConfig üzerinde yapılan değişiklikler bir sonraki içerik yüklemesinde değerlendirilir. SDK, PlaybackConfig öğesini değiştirmek için aşağıdaki yöntemleri sağlar.

• CastReceiverContext'ı başlatırken varsayılan yapılandırma seçeneklerini geçersiz kılmak için CastReceiverOptions.playbackConfig
• PlayerManager.getPlaybackConfig()
• PlayerManager.setPlaybackConfig() simgesini tıklayarak mevcut yapılandırmayı geçersiz kılabilirsiniz. Bu ayar, sonraki tüm yüklemelere veya tekrar geçersiz kılınana kadar uygulanır.
• PlayerManager.setMediaPlaybackInfoHandler() simgesini tıklayarak yalnızca mevcut yapılandırmaların üzerine yüklenen medya öğesi için ek yapılandırmalar uygulayabilirsiniz. İşleyici, oynatıcı oluşturulmadan hemen önce çağrılır. Burada yapılan değişiklikler kalıcı değildir ve getPlaybackConfig() için yapılan sorgulara dahil edilmez. Sonraki medya öğesi yüklendiğinde bu işleyici tekrar çağrılır.

Aşağıdaki örnekte, CastReceiverContext başlatılırken PlaybackConfig değerinin nasıl ayarlanacağı gösterilmektedir. Yapılandırma, manifest elde etmek için gönderilen istekleri geçersiz kılar. İşleyici, CORS erişim denetimi isteklerinin çerezler veya yetkilendirme başlıkları gibi kimlik bilgileri kullanılarak yapılması gerektiğini belirtir.

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

Aşağıdaki örnekte, PlayerManager içinde sağlanan alıcı ve ayarlayıcı kullanılarak PlaybackConfig'ün nasıl geçersiz kılınacağı gösterilmektedir. Bu ayar, oynatıcının 1 segment yüklendikten sonra içerik oynatmayı devam ettirmesi için yapılandırılır.

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

Aşağıdaki örnekte, medya oynatma bilgileri işleyicisi kullanılarak belirli bir yükleme isteği için PlaybackConfig değerinin nasıl geçersiz kılınacağı gösterilmektedir. İşleyici, geçerli öğenin contentId öğesinden licenseUrl öğesini almak için uygulama tarafından uygulanan bir getLicenseUrlForMedia yöntemini çağırır.

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

Etkinlik işleyici

Web Receiver SDK'sı, Web Receiver uygulamanızın oynatıcı etkinliklerini işlemesine olanak tanır. Etkinlik dinleyicisi, dinleyiciyi tetiklemesi gereken etkinlikleri belirten bir cast.framework.events.EventType parametresi (veya bu parametrelerin bir dizisi) alır. Hata ayıklama için yararlı olan önceden yapılandırılmış cast.framework.events.EventType dizilerini cast.framework.events.category bölümünde bulabilirsiniz. Etkinlik parametresi, etkinlik hakkında ek bilgiler sağlar.

Örneğin, bir mediaStatus değişikliğinin ne zaman yayınlandığını bilmek istiyorsanız etkinliği işlemek 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
});

Mesajın ele geçirilmesi

Web Alıcısı SDK'sı, Web Alıcısı uygulamanızın mesajları durdurmasına ve bu mesajlarda özel kod yürütmesine olanak tanır. Mesaj tutucu, hangi tür mesajın yakalanacağını belirten bir cast.framework.messages.MessageType parametresi alır.

Engelleyici, değiştirilmiş isteği veya değiştirilmiş istek değeriyle çözülen bir Promise döndürmelidir. null döndürmek, varsayılan ileti işleyicinin çağrılmasını engeller. Daha fazla bilgi için Medya yükleme bölümüne bakın.

Örneğin, yükleme isteği verilerini değiştirmek istiyorsanız isteği durdurup değiştirmek için aşağıdaki mantığı kullanabilirsiniz:

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 tutucuda hata oluştuğunda Web Alıcı uygulamanız uygun bir cast.framework.messages.ErrorType ve cast.framework.messages.ErrorReason döndürmelidir.

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ın yakalanması ve etkinlik işleyici

Mesajın yakalanması ile etkinlik dinleyicisi arasındaki bazı önemli farklar şunlardır:

• Etkinlik dinleyicileri, istek verilerini değiştirmenize izin vermez.
• Etkinlik dinleyiciler, en iyi şekilde analizleri veya özel bir işlevi tetiklemek için kullanılır.

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

• Mesajın dinlenmesi, mesajın kesilmesi ve istek verilerinin değiştirilmesi için mesajın kesilmesi gerekir.
• Mesajları durdurma özelliği, istek verileriyle ilgili özel mantığı işlemek için en iyi şekilde kullanılır.

Medya yükleme

MediaInformation cast.framework.messages.MessageType.LOAD mesajına medya yüklemek için entity, contentUrl ve contentId gibi birçok özellik sağlar.

• entity, hem gönderen hem de alıcı uygulamalarınız için uygulamanızda kullanmanız önerilen mülktür. Mülk, oynatma listesi veya medya içeriği olabilecek bir derin bağlantı URL'sidir. Uygulamanız bu URL'yi ayrıştırmalı ve diğer iki alandan en az birini doldurmalıdır.
• contentUrl, oynatıcının içeriği yüklemek için kullanacağı oynatılabilir URL'ye karşılık gelir. Örneğin, bu URL bir DASH manifestini işaret edebilir.
• contentId, oynatılabilir bir içerik URL'si (contentUrl mülküne benzer) veya yüklenen içeriğin ya da oynatma listesinin benzersiz tanımlayıcısıdır. Bu mülk tanımlayıcısı olarak kullanılıyorsa uygulamanız contentUrl içinde oynatılabilir bir URL doldurmalıdır.

Gerçek kimliği veya anahtar parametrelerini depolamak için entity, medyanın URL'si için ise contentUrl kullanmanızı öneririz. Bunun bir örneği, LOAD isteğinde entity'ün bulunduğu ve oynatılabilir contentUrl'in alındığı aşağıdaki snippet'te 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 ona bağlı video veya ses cihazı hakkında cihaz bilgilerini sağlar. getDeviceCapabilities yöntemi, Google Asistan, Bluetooth, bağlı ekran ve ses cihazları için destek bilgileri sağlar.

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

Bu örnekte, web alıcı cihazın sırasıyla IS_HDR_SUPPORTED ve IS_DV_SUPPORTED tuşlarıyla HDR ve DolbyVision (DV) oynatıp oynatamayacağını kontrol edilir.

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ılar, gönderen uygulamaları (Web, Android ve iOS), Asistan özellikli cihazlardaki sesli komutlar, akıllı ekranlardaki dokunmatik kontroller ve Android TV cihazlardaki uzaktan kumandalar aracılığıyla Web Alıcısı uygulamanızla etkileşim kurabilir. Cast SDK'sı, Web Alıcısı uygulamasının bu etkileşimleri yönetmesine, kullanıcı işlemi durumları aracılığıyla uygulama kullanıcı arayüzünü güncellemesine ve isteğe bağlı olarak değişiklikleri göndererek arka uç hizmetlerini güncellemesine olanak tanıyan çeşitli API'ler sağlar.

Desteklenen medya komutları

Kullanıcı arayüzü kontrol durumları, iOS ve Android gönderen genişletilmiş denetleyiciler, dokunmatik cihazlarda çalışan alıcı ve uzaktan kumanda uygulamaları ve Android TV cihazlarındaki alıcı uygulamaları için MediaStatus.supportedMediaCommands tarafından yönlendirilir. Mülkte belirli bir bit Command etkinleştirildiğinde, bu işlemle ilgili düğmeler de etkinleştirilir. Değer ayarlanmazsa düğme devre dışı bırakılır. Bu değerler web alıcısında aşağıdaki yöntemlerle değiştirilebilir:

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

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

Alıcı, güncellenmiş MediaStatus dosyasını hazırladığında supportedMediaCommands mülkünde yapılan değişiklikleri de ekler. Durum yayınlandığında bağlı gönderen uygulamaları, kullanıcı arayüzündeki düğmeleri buna göre günceller.

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

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

Kullanıcılar kullanıcı arayüzüyle etkileşime geçtiğinde veya sesli komut gönderdiğinde, oynatılan içeriğin oynatılmasını ve oynatılan öğeyle ilgili özellikleri kontrol edebilirler. Oynatma işlemini kontrol eden istekler SDK tarafından otomatik olarak işlenir. Oynatılan öğenin özelliklerini değiştiren istekler (ör. LIKE komutu) 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ğıdakiler yapılmalıdır:

• Bir medya öğesi yüklenirken MediaInformation userActionStates kullanıcı tercihlerine göre ayarlayın.
• USER_ACTION mesajlarını durdurun ve istenen işlemi belirleyin.
• Kullanıcı arayüzünü güncellemek için MediaInformation UserActionState öğesini güncelleyin.

Aşağıdaki snippet, LOAD isteğini durdurur ve LoadRequestData'un MediaInformation değerini doldurur. Bu durumda kullanıcı, yüklenen içeriği beğenir.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

Aşağıdaki snippet, USER_ACTION mesajını durdurur ve istenen değişiklikle arka uç çağrısını işler. Ardından, alıcıdaki UserActionState öğesini güncellemek için bir arama yapar.

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, arka uç hizmetine yapılan bir çağrıyı simüle etmektedir. İş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 destekliyorsa 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 UserActionState öğesini MediaInformation öğesine ekler veya MediaInformation öğesinden kaldırır. MediaInformation öğesinin UserActionState özelliğini güncellemek, istenen işlemle ilişkili düğmenin durumunu değiştirir. Bu değişiklik akıllı ekran kontrollerinin kullanıcı arayüzüne, uzaktan kumanda uygulamasına ve Android TV kullanıcı arayüzüne yansıtılmıştır. Ayrıca, iOS ve Android gönderenler için genişletilmiş denetleyicinin kullanıcı arayüzünü güncellemek üzere giden MediaStatus mesajları aracılığıyla 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

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

Sesli olarak desteklenen medya komutları

Bir sesli komutun, Asistan özellikli bir cihazda medya komutunu tetiklemesini önlemek için öncelikle desteklemeyi planladığınız desteklenen medya komutlarını ayarlamanız gerekir. Ardından, CastReceiverOptions.enforceSupportedCommands mülkünü etkinleştirerek bu komutları uygulamanız gerekir. Cast SDK'sı gönderenlerindeki ve dokunmatik ekranlı cihazlardaki kullanıcı arayüzü, bu yapılandırmaları yansıtacak şekilde değişecek. İşaretçi etkinleştirilmezse gelen sesli komutlar yürütülür.

Örneğin, gönderen uygulamalarınızdan ve dokunmatik ekranlı cihazlardan PAUSE'e 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 edilmeyen tüm gelen sesli komutlar atlanır.

Aşağıdaki örnekte, CastReceiverContext başlatırken CastReceiverOptions değerini sağlıyoruz. PAUSE komutu için destek ekledik ve oynatıcının yalnızca bu komutu desteklemesini zorunlu kıldık. Artık bir sesli komut SEEK gibi başka bir işlem isterse 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ı mantık uygulayabilirsiniz. enforceSupportedCommands işaretini kaldırın ve kısıtlamak istediğiniz her komut için gelen iletiyi durdurabilirsiniz. Burada, Asistan özellikli cihazlara gönderilen SEEK komutlarının Web Alıcı uygulamanızda arama tetiklememesi için SDK tarafından sağlanan isteği durduruyoruz.

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;
  });

Sesli etkinlikten arka plana geçme

Cast platformu, kullanıcı konuşmasını dinleme veya yanıt verme gibi Asistan etkinlikleri nedeniyle uygulamanızın sesini arka plana alırsa etkinlik başladığında Web Alıcı uygulamasına NOT_IN_FOCUS mesajı gönderilir.FocusState Etkinlik sona erdiğinde IN_FOCUS içeren başka bir mesaj gönderilir. Uygulamanıza ve oynatılan medyaya bağlı olarak, FOCUS_STATE mesaj türünü arayarak FocusState NOT_IN_FOCUS olduğunda medyayı duraklatmak isteyebilirsiniz.

Örneğin, Asistan bir kullanıcı sorgusuna yanıt veriyorsa sesli kitabın oynatılmasını duraklatmak iyi bir kullanıcı deneyimidir.

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 belirtmezse altyazılar için kullanılan dil, komutun söylendiği dildir. Bu senaryolarda, gelen mesajın isSuggestedLanguage parametresi, ilişkili dilin kullanıcı tarafından önerildiğini veya açıkça istendiğini belirtir.

Örneğin, "Ok Google, altyazıları aç" komutu için isSuggestedLanguage, komutun söylendiği dile göre belirlendiği için true olarak ayarlanır. Dil açıkça istenirse (ör. "Ok Google, İngilizce altyazıları aç") isSuggestedLanguage, false olarak ayarlanır.

Meta veriler ve sesli yayınlama

Sesli komutlar varsayılan olarak web alıcısı tarafından işlenir. Bununla birlikte, içeriğinizin meta verilerinin eksiksiz ve doğru olduğundan emin olmanız gerekir. Bu sayede sesli komutlar Asistan tarafından düzgün şekilde işlenir ve meta veriler Google Home uygulaması gibi yeni arayüz türlerinde ve Google Home Hub gibi akıllı ekranlarda düzgün şekilde gösterilir.

Akış aktarma

Oturum durumunu korumak, kullanıcıların sesli komutları, Google Home uygulaması 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) oynatmayı durdurur ve başka bir cihazda (hedef) oynatmaya devam eder. En son donanım yazılımına sahip tüm Cast cihazları, yayın aktarımında kaynak veya hedef olarak kullanılabilir.

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

1. Kaynak cihazda:
   1. Medya oynatmayı durdurur.
   2. Web Alıcısı uygulaması, mevcut medya durumunu kaydetme komutu alır.
   3. Web alıcı uygulaması kapatılır.
2. Hedef cihazda:
   1. Web alıcı uygulaması yüklenir.
   2. Web Alıcısı uygulaması, kayıtlı medya durumunu geri yükleme komutu alır.
   3. Medya oynatılmaya devam eder.

Medya durumunun öğeleri şunlardır:

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

Akış aktarmayı etkinleştirme

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

1. STREAM_TRANSFER komutunu kullanarak supportedMediaCommands dosyasını güncelleyin:

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

2. İsteğe bağlı olarak, SESSION_STATE ve RESUME_SESSION ileti müdahalecilerini Oturum durumunu koruma bölümünde açıklandığı şekilde geçersiz kılabilirsiniz. Yalnızca özel verilerin oturum anlık görüntüsünün bir parçası olarak depolanması gerekiyorsa bunları 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 Receiver SDK'sı, Web Receiver uygulamalarının mevcut medya durumunun anlık görüntüsünü alarak, durumu bir yükleme isteğine dönüştürerek ve yükleme isteğiyle oturumu devam ettirerek oturum durumlarını koruması için varsayılan bir uygulama sağlar.

Web alıcı tarafından oluşturulan yükleme isteği, gerekirse SESSION_STATE mesaj tutucuda geçersiz kılınabilir. Yükleme isteğine özel veri eklemek istiyorsanız bunları loadRequestData.customData içine koymanızı ö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 ileti tutucudaki 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 önceden yükleme

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

Ön yükleme işlemi, yaklaşan öğelerin birkaç segmentini önceden indirir. Spesifikasyon, QueueItem nesnesinde bulunan preloadTime değerinde yapılır (sağlanmazsa varsayılan olarak 20 saniyedir). Zaman, şu anda oynatılan öğenin sonuna göre saniye cinsinden ifade edilir . Yalnızca pozitif değerler geçerlidir. Örneğin, değer 10 saniye ise bu öğe, önceki öğe bitmeden 10 saniye önce önceden yüklenir. Önceden yükleme süresi, currentItem öğesinde kalan süreden uzunsa önceden yükleme işlemi mümkün olan en kısa sürede gerçekleşir. Bu nedenle, queueItem üzerinde çok büyük bir ön yükleme değeri belirtilirse mevcut öğeyi oynatırken bir sonraki öğeyi de önceden yüklemiş oluruz. Ancak bu değer, oynatılan öğenin bant genişliğini ve akış performansını etkileyebileceğinden, bu ayarı ve seçimi geliştiriciye bırakırız.

Ön yükleme, varsayılan olarak HLS, DASH ve Smooth Streaming içerikleri için çalışır.

Cast cihazları yalnızca bir medya öğesini desteklediği ve mevcut bir içerik öğesi oynatılmaya devam ederken ön yükleme yapmak için kullanılamadığı için normal MP4 video ve ses dosyaları (ör. MP3) ön yüklenmez.

Özel mesajlar

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

Gönderen, çalıştırmakta olduğu platformun (Android, iOS, Web) gönderen API'lerini kullanarak bir web alıcısına mesaj gönderir. Etkinlik dinleyicilerine iletilen etkinlik nesnesi (bir mesajın tezahürü olan), verilerin belirli etkinlik türünün özelliklerini aldığı bir veri öğesine (event.data) sahiptir.

Web alıcı uygulaması, belirli bir ad alanındaki mesajları dinlemeyi seçebilir. Bu nedenle, Web Alıcısı uygulamasının bu ad alanı protokolünü desteklediği söylenir. Ardından, bu ad alanında iletişim kurmak isteyen bağlı gönderenlerin uygun protokolü kullanması gerekir.

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".

Web Alıcısı'nın, bağlı gönderenlerden gelen özel mesajları dinlemek için kullanabileceği kod snippet'i aşağıda 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 mesaj göndererek gönderenleri web alıcısının durumu hakkında bilgilendirebilir. Web alıcı uygulaması, CastReceiverContext üzerinde sendCustomMessage(namespace, senderId, message) kullanarak mesaj gönderebilir. Web alıcısı, alınan bir mesaja yanıt olarak veya uygulama durumundaki bir değişiklik nedeniyle tek bir gönderene mesaj gönderebilir. Web alıcıları, noktadan noktaya mesajlaşmanın (64 KB sınırı ile) yanı sıra bağlı tüm gönderenlere mesaj da yayınlayabilir.

Ses cihazları için yayınlama

Yalnızca ses oynatmayla ilgili destek için Ses cihazları için Google Cast kılavuzuna bakın.

Android TV

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

Uygulamanızı uzaktan kumandayla entegre etme

Android TV cihazında çalışan Google Web Alıcısı, cihazın kontrol girişlerinden (ör. el tipi uzaktan kumanda) gelen girişleri Medya Oynatımı Mesajları bölümünde açıklandığı gibi urn:x-cast:com.google.cast.media ad alanının tanımlandığı medya oynatma mesajları olarak çevirir. Android TV'nin kontrol girişlerinden temel oynatma denetimine izin vermek için uygulamanızın, uygulama medya oynatmasını kontrol etmek üzere bu mesajları desteklemesi gerekir.

Android TV uyumluluğuyla ilgili kurallar

Uygulamanızın Android TV ile uyumlu olmasını sağlamak için kaçınmanız 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 algıladığı için yalnızca mobil cihazlara yönelik bir siteye yönlendirebilir. Kullanıcı aracısı dizesindeki "Android" ifadesinin her zaman mobil kullanıcıyı gösterdiğini varsaymayın.
• Android'in medya paketi, verileri almak için şeffaf GZIP kullanabilir. Medya verilerinizin Accept-Encoding: gzip'e yanıt verebileceğinden emin olun.
• Android TV HTML5 medya etkinlikleri, Chromecast'ten farklı zamanlamalarda tetiklenebilir. Bu durum, Chromecast'te gizli olan sorunları ortaya çıkarabilir.
• Medyayı güncellerken timeupdate, pause ve waiting gibi <audio>/<video>öğeleri tarafından tetiklenen medyayla ilgili etkinlikleri kullanın. Platforma bağımlı olma eğiliminde olduklarından progress, suspend ve stalled gibi ağ oluşturmayla ilgili etkinlikleri kullanmaktan kaçının. Alıcınızda medya etkinliklerini işleme hakkında daha fazla bilgi için Medya etkinlikleri başlıklı makaleyi inceleyin.
• Alıcı sitenizin HTTPS sertifikalarını yapılandırırken ara CA sertifikalarını eklediğinizden emin olun. Doğrulamak için Qualsys SSL test sayfasına bakı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 dahil diğer Cast platformları sayfayı 1080p'ye kadar gösterebilir. Alıcınızın sayfasının farklı çözünürlüklerde sorunsuz şekilde ölçeklendirildiğinden emin olun.