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

Bu sayfada, özel bir web alıcı 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. cast-media-player, background-image ve splash-image gibi çeşitli kullanıcı arayüzü öğelerini biçimlendirmek için font-family öğesine yönelik CSS benzeri özel stil.
3. Web alıcı çerçevesini yüklemek için kullanılan bir komut dosyası öğesi.
4. Mesajları yakalamak ve etkinlikleri işlemek için JavaScript kodu.
5. Otomatik oynatma için sıraya ekleme
6. Oynatmayı 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ıştaki sınıftır ve temel kitaplıkların yüklenmesini yönetip Web Alıcı SDK'sının başlatılmasını sağlar. SDK, uygulama geliştiricilerin SDK'yı CastReceiverOptions aracılığıyla 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, bir gönderen bağlantısının hâlâ etkin olarak bağlı olup olmadığını algılamaya yönelik varsayılan davranışın nasıl geçersiz kılınacağı gösterilmektedir. Web alıcısı, maxInactivity saniye boyunca bir gönderenle iletişim kuramadığında SENDER_DISCONNECTED etkinliği gönderilir. Aşağıdaki yapılandırma bu zaman aşımını geçersiz kılar. Bu, Web Alıcı uygulamasının IDLE durumunda bağlı gönderen olmadığında Chrome uzaktan hata ayıklama oturumunu kapatmasını önlediği için sorunları ayıklarken 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, 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 sunar. Bu bilgiler, PlayerManager tarafından işlenir ve oyuncular oluşturulurken değerlendirilir. Yeni bir yük Web Receiver SDK'ya her iletildiğinde oynatıcılar oluşturulur. Oynatıcı oluşturulduktan sonra yapılan PlaybackConfig değişiklikleri, bir sonraki içerik yüklemede değerlendirilir. SDK, PlaybackConfig öğesini değiştirmek için aşağıdaki yöntemleri sağlar.

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

Aşağıdaki örnekte, PlaybackConfig başlatılırken CastReceiverContext değerinin nasıl ayarlanacağı gösterilmektedir. Yapılandırma, manifest alma için giden istekleri geçersiz kılar. İşleyici, CORS Access-Control isteklerinin çerezler veya yetkilendirme başlıkları gibi kimlik bilgileri kullanılarak yapılmasını 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ın nasıl geçersiz kılınacağı gösterilmektedir. Bu ayar, oynatıcıyı 1 segment yüklendikten sonra içerik oynatmaya devam edecek şekilde yapılandırı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 bilgisi işleyicisini kullanarak 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 değerinden licenseUrl değerini almak için uygulamada 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, Web Receiver uygulamanızın oynatıcı etkinliklerini işlemesine olanak tanır. Etkinlik dinleyici, dinleyiciyi tetikleyecek 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 içinde bulabilirsiniz. Etkinlik parametresi, etkinlik hakkında ek bilgiler sağlar.

Örneğin, bir mediaStatus değişikliğinin yayınlanma zamanını öğrenmek 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 yakalama

Web Receiver SDK, Web Receiver uygulamanızın mesajları yakalamasına ve bu mesajlarda özel kod yürütmesine olanak tanır. Mesaj yakalayıcı, hangi tür mesajın yakalanması gerektiğini belirten bir cast.framework.messages.MessageType parametresi alır.

Arayıcı, değiştirilmiş isteği veya değiştirilmiş istek değeriyle çözümlenen bir Promise'i döndürmelidir. null döndürülmesi, 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 bunları yakalayıp 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 yakalayıcıda hatalar oluştuğunda Web Receiver 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 yakalama ve etkinlik işleyici

Mesaj yakalama ile etkinlik dinleyici arasındaki bazı önemli farklar şunlardır:

• Bir etkinlik dinleyicisi, istek verilerini değiştirmenize izin vermez.
• Etkinlik işleyici, 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 yakalama, bir mesajı dinlemenize, yakalamanıza ve istek verilerinin kendisini değiştirmenize olanak tanır.
• Mesaj yakalama, istek verileriyle ilgili özel mantığı işlemek için en iyi yöntemdir.

Medya yükleniyor

MediaInformation entity, contentUrl ve contentId dahil olmak üzere cast.framework.messages.MessageType.LOAD mesajına medya yüklemek için çeşitli özellikler sunar.

• entity, hem gönderen hem de alıcı uygulamalarınız için uygulamanızda kullanılması önerilen özelliktir. Mülk, oynatma listesi veya medya içeriği olabilen 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 özelliği, oynatılabilir bir içerik URL'si (contentUrl özelliğine benzer) veya yüklenen içerik ya da oynatma listesi için benzersiz bir tanımlayıcı olabilir. Bu özelliği tanımlayıcı olarak kullanıyorsanız 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 önerilir. Bunun bir örneği, aşağıdaki snippet'te gösterilmektedir. Burada entity, LOAD isteğinde yer alıyor ve oynatılabilir contentUrl alınıyor:

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 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, belirtilen numaralandırılmış değerlerden birini ileterek sorgulayabileceğiniz bir nesne döndürür. Böylece, bu numaralandırılmış değer için cihazın özelliğini alabilirsiniz. Numaralandırılmış değerler, 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 Dolby Vision (DV) oynatıp oynatamadığı 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 cihazlarındaki uzaktan kumandalar aracılığıyla Web Alıcı uygulamanızla etkileşimde bulunabilir. Cast SDK, Web Alıcı uygulamasının bu etkileşimleri işlemesine, 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ş denetleyicileri, dokunmatik cihazlarda çalışan alıcı ve uzaktan kumanda uygulamaları ile Android TV cihazlardaki alıcı uygulamaları için MediaStatus.supportedMediaCommands tarafından belirlenir. Bir özellik için belirli bir bit düzeyinde Command etkinleştirildiğinde, bu işlemle ilgili düğmeler etkinleştirilir. Değer ayarlanmamışsa düğme devre dışı bırakılır. Bu değerler, Web alıcısında şu şekilde değiştirilebilir:

1. Belirli Commands değerini ayarlamak için PlayerManager.setSupportedMediaCommands kullanma
2. addSupportedMediaCommands kullanarak yeni 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 hazırladığında bu, supportedMediaCommands mülkündeki değişiklikleri içerir. Durum yayınlandığında, bağlı gönderen uygulamaları kullanıcı arayüzlerindeki düğmeleri buna göre günceller.

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

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

Kullanıcılar, kullanıcı arayüzüyle etkileşim kurduğunda veya sesli komut gönderdiğinde içeriğin oynatılmasını ve oynatılan öğeyle ilgili özellikleri kontrol edebilir. Oynatmayı kontrol eden istekler SDK tarafından otomatik olarak işlenir. Çalınan öğenin özelliklerini değiştiren istekler (ör. LIKE komutu) alıcı uygulama tarafından işlenmelidir. SDK, bu tür istekleri işlemek için bir dizi API sağlar. Bu isteklerin desteklenmesi için aşağıdakilerin yapılması gerekir:

• Bir medya öğesi yüklenirken kullanıcının tercihlerine göre MediaInformation userActionStates ayarlayın.
• USER_ACTION iletilerine müdahale edin 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 yakalar ve LoadRequestData'nin 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ı yakalar ve istenen değişiklikle arka uca yapılan çağrıyı işler. Ardından, alıcıdaki UserActionState 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, bir arka uç hizmetine yapılan ç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 bir 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 değerini alır ve UserActionState değerini MediaInformation değerine ekler veya MediaInformation değerinden kaldırır. UserActionState değerinin güncellenmesi, istenen işlemle ilişkili düğmenin durumunu değiştirir.MediaInformation Bu değişiklik, akıllı ekran kontrolleri kullanıcı arayüzüne, uzaktan kumanda uygulamasına ve Android TV kullanıcı arayüzüne yansıtılı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 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

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

Sesle desteklenen medya komutları

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 özelliğini etkinleştirerek bu komutları zorunlu kılmanız gerekir. Cast SDK gönderenlerindeki ve dokunma özellikli cihazlardaki kullanıcı arayüzü, bu yapılandırmaları yansıtacak şekilde değişir. İşaret etkinleştirilmezse gelen sesli komutlar yürütülür.

Örneğin, gönderen uygulamalarınızda ve dokunma özellikli cihazlarınızda PAUSE özelliğine izin veriyorsanız alıcınızı da bu ayarları yansıtacak şekilde yapılandırmanız gerekir. Yapılandırıldığında, desteklenen komutlar listesinde yer almayan tüm gelen sesli komutlar bırakılır.

Aşağıdaki örnekte, CastReceiverContext başlatılırken CastReceiverOptions sağlanmaktadır. 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 bu istek 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
});

Sınırlamak istediğiniz her komut için ayrı bir mantık uygulayabilirsiniz. enforceSupportedCommands işaretini kaldırın ve kısıtlamak istediğiniz her komut için gelen iletiyi engelleyebilirsiniz. Burada, SDK tarafından sağlanan isteği yakalıyoruz. Böylece, Asistan özellikli cihazlara verilen SEEK komutları, Web Receiver uygulamanızda arama işlemini tetiklemez.

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 geri konuşma gibi Asistan etkinliği nedeniyle uygulamanızın sesini arka plana atarsa etkinlik başladığında Web Alıcı uygulamasına FocusState NOT_IN_FOCUS 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 olduğunda FOCUS_STATE mesaj türünü yakalayarak medyayı duraklatmak isteyebilirsiniz.

Örneğin, Asistan bir kullanıcı sorgusuna yanıt veriyorsa sesli kitap oynatmayı 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 belirtmediğinde, altyazılarda kullanılan dil, komutun konuşulduğu dildir. Bu senaryolarda, gelen mesajın isSuggestedLanguage parametresi, ilişkili dilin önerilip önerilmediğini veya kullanıcı tarafından açıkça istenip istenmediğini gösterir.

Örneğin, "OK Google, altyazıları aç" komutunda isSuggestedLanguage, true olarak ayarlanır. Bunun nedeni, dilin komutun konuşulduğu dilden çıkarılmasıdır. Dil açıkça isteniyorsa (ör. "Ok Google, İngilizce altyazıları aç"), isSuggestedLanguage değeri false olarak ayarlanır.

Meta veriler ve ses aktarımı

Sesli komutlar varsayılan olarak Web Receiver tarafından işlenirken içeriğinizin meta verilerinin eksiksiz ve doğru olduğundan emin olmanız gerekir. Bu sayede, sesli komutların Asistan tarafından düzgün şekilde işlenmesi ve meta verilerin Google Home uygulaması ile Google Home Hub gibi akıllı ekranlar gibi yeni arayüz türlerinde düzgün şekilde gösterilmesi sağlanır.

Akış aktarma

Oturum durumunu koruma, akış aktarımının temelini oluşturur. Bu özellik sayesinde kullanıcılar, sesli komutları, Google Home uygulaması veya akıllı ekranları kullanarak mevcut ses ve video akışlarını cihazlar arasında taşıyabilir. Medya, bir cihazda (kaynak) oynatmayı durdurur ve başka bir cihazda (hedef) oynatmaya devam eder. En yeni donanım yazılımına sahip tüm Cast cihazlar, akış aktarımında kaynak veya hedef olarak kullanılabilir.

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

1. Kaynak cihazda:
   1. Medya oynatmayı durdurur.
   2. Web alıcı 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ı uygulaması, kaydedilen 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 kuyruktaki (ör. oynatma listesi veya sanatçı radyosu) yeri
• Kimliği doğrulanmış kullanıcı.
• Oynatma durumu (ör. oynatılıyor veya duraklatıldı)

Akış aktarma özelliğini etkinleştirme

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

1. STREAM_TRANSFER komutuyla supportedMediaCommands uygulamasını 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 yakalayıcılarını 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ı korumaya yönelik varsayılan uygulama, akış aktarımını destekler.

Oturum durumunu koruma

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

Gerekirse Web Receiver tarafından oluşturulan yükleme isteği, SESSION_STATE mesajı yakalayıcıda geçersiz kılınabilir. Yükleme isteğine özel veriler eklemek istiyorsanız bunları loadRequestData.customData içine 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 ileti önleyici içinde loadRequestData.customData konumundan 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ı, kuyruktaki mevcut oynatma öğesinden sonraki medya öğelerinin önceden yüklenmesini destekler.

Ön yükleme işlemi, yaklaşan öğelerin birkaç segmentini önceden indirir. Belirtme işlemi, QueueItem nesnesindeki preloadTime değeriyle yapılır (sağlanmazsa varsayılan olarak 20 saniye). Süre, saniye cinsinden ifade edilir ve şu anda oynatılan öğenin sonuna göre belirlenir . 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'da kalan süreden daha uzunsa önceden yükleme mümkün olan en kısa sürede gerçekleşir. Bu nedenle, queueItem'da çok büyük bir önceden yükleme değeri belirtilirse mevcut öğeyi oynatırken bir sonraki öğeyi önceden yükleme etkisi elde edilebilir. Ancak bu değer, oynatılan öğenin bant genişliğini ve yayın performansını etkileyebileceğinden bu ayarı ve seçimi geliştiriciye bırakıyoruz.

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

MP3 gibi normal MP4 video ve ses dosyaları önceden yüklenmez. Cast cihazlar yalnızca bir medya öğesini destekler ve mevcut bir içerik öğesi oynatılırken önceden yükleme için kullanılamaz.

Özel mesajlar

İleti değişimi, Web Alıcı uygulamaları için temel etkileşim yöntemidir.

Bir gönderen, çalıştığı platformun (Android, iOS, Web) gönderen API'lerini kullanarak bir Web alıcısına mesaj gönderir. Etkinlik işleyicilere iletilen etkinlik nesnesinde (mesajın gösterimi) verilerin belirli etkinlik türünün özelliklerini aldığı bir veri öğesi (event.data) bulunur.

Bir Web Receiver uygulaması, belirli bir ad alanındaki mesajları dinlemeyi seçebilir. Bu sayede, Web Alıcı uygulamasının söz konusu ad alanı protokolünü desteklediği söylenir. Bu durumda, söz konusu 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 herhangi bir dizeyle devam eden "urn:x-cast:" ile başlamalıdır. Örneğin, "urn:x-cast:com.example.cast.mynamespace".

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

Ses cihazlarında yayın yapma

Yalnızca ses oynatma konusunda destek için Ses cihazları için Google Cast rehberine bakın.

Android TV

Bu bölümde, Google Web Receiver'ın girişlerinizi oynatma olarak 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. elde tutulan uzaktan kumanda) gelen girişleri, Medya Oynatma Mesajları bölümünde açıklandığı gibi urn:x-cast:com.google.cast.media ad alanı için tanımlanan medya oynatma mesajları olarak çevirir. Android TV'nin kontrol girişlerinden temel oynatma kontrolüne izin vermek için uygulamanız, uygulama medya oynatmasını kontrol etmek üzere bu mesajları desteklemelidir.

Android TV uyumluluğu yönergeleri

Uygulamanızın Android TV ile uyumlu olmasını sağlamak için bazı öneriler ve kaçınılması gereken yaygın hatalar:

• Kullanıcı aracısı dizesinin hem "Android" hem de "CrKey" içerdiğini unutmayın. Bazı siteler, "Android" etiketini algıladıkları için yalnızca mobil cihazlara yönelik bir siteye yönlendirme yapabilir. Kullanıcı aracısı dizesindeki "Android"in her zaman mobil kullanıcıyı gösterdiğini varsaymayın.
• Android'in medya yığını, veri getirmek için şeffaf GZIP'i kullanabilir. Medya verilerinizin Accept-Encoding: gzip yanıt verebildiğinden emin olun.
• Android TV HTML5 medya etkinlikleri, Chromecast'ten farklı zamanlarda tetiklenebilir. Bu durum, Chromecast'te gizli olan sorunları ortaya çıkarabilir.
• Medya güncellenirken <audio>/<video> gibi öğeler tarafından tetiklenen medya ile ilgili etkinlikleri kullanın.timeupdatepausewaiting Ağ ile ilgili etkinlikleri (ör. progress, suspend ve stalled) kullanmaktan kaçının. Bu etkinlikler platforma bağlı olma eğilimindedir. Alıcınızdaki 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. Aşağıdakileri 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 çözünürlükte gösterebilir. Alıcı sayfanızın farklı çözünürlüklerde düzgün şekilde ölçeklendiğinden emin olun.