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

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

  1. Web Alıcısı ile 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 öğesine yönelik özel CSS benzeri stil.
  3. Web Alıcı çerçevesini yüklemek için bir komut dosyası öğesi.
  4. Mesajları yakalamak ve etkinlikleri işlemek için JavaScript kodu.
  5. Otomatik oynatma için sıraya eklenir.
  6. Oynatmayı yapılandırma seçenekleri.
  7. Web Alıcısı bağlamını ayarlama seçenekleri.
  8. Web Alıcısı uygulaması tarafından desteklenen komutları ayarlama seçenekleri.
  9. Web Alıcısı 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. Temel kitaplıkların yüklenmesini yönetir ve Web Alıcı SDK'sının başlatılmasını sağlar. SDK, uygulama geliştiricilerin CastReceiverOptions aracılığıyla 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ındaki isteğe bağlı parametre ayarlanırken SDK'ya iletilir.

Aşağıdaki örnekte, gönderen bağlantısının hâlâ etkin bir şekilde bağlı olup olmadığını algılamayla ilgili 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, sorunları ayıklarken yararlı olabilir. Çünkü Web Alıcısı uygulamasının, IDLE durumunda bağlı gönderen olmadığında Chrome Uzaktan Hata Ayıklayıcı oturumunu kapatmasını engeller.

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 Alıcı SDK'sı, içerik yüklerken DRM bilgileri, yeniden deneme yapılandırmaları ve istek işleyiciler 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. Oynatıcılar, Web Alıcı SDK'sına her yeni yükleme iletildiğinde 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 sunar.

  • CastReceiverOptions.playbackConfig kullanarak varsayılan yapılandırma seçeneklerini geçersiz kılabilirsiniz CastReceiverContext.
  • PlayerManager.getPlaybackConfig() komutunu çalıştırın.
  • Mevcut yapılandırmayı geçersiz kılmak için PlayerManager.setPlaybackConfig(). Bu ayar, sonraki tüm yüklemelere uygulanır veya tekrar geçersiz kılınana kadar geçerli olur.
  • PlayerManager.setMediaPlaybackInfoHandler() yalnızca yüklenen medya öğesi için mevcut yapılandırmaların üzerine ek yapılandırmalar uygulamak için kullanılır. İş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. Bir 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, manifestleri almak 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ı 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 değerinin nasıl geçersiz kılınacağı gösterilmektedir. Bu ayar, oynatıcıyı 1 segment yüklendikten sonra içerik oynatmayı devam ettirecek ş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ş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 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 Alıcısı SDK'sı, Web Alıcısı uygulamanızın oynatıcı etkinliklerini işlemesine olanak tanır. Etkinlik işleyici, işleyiciyi 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 dizileri cast.framework.events.category içinde bulunabilir. Etkinlik parametresi, etkinlikle ilgili ek bilgiler sağlar.

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

Mesajları ele geçirme

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

Yakalayıcı, değiştirilen isteği veya değiştirilen istek değeriyle çözümlenen bir Promise döndürmelidir. null döndürülmesi, varsayılan mesaj işleyicinin çağrılmasını engeller. Daha fazla bilgi için Medya yükleme bölümünü inceleyin.

Örneğin, yükleme isteği verilerini değiştirmek istiyorsanız bu verileri 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 hata oluştuğunda Web Alıcısı 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;
        });
    });

Mesajları yakalama ve etkinlik işleyici karşılaştırması

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

  • Etkinlik işleyici, 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);
    });
  • Mesajları yakalama özelliği, mesajları dinlemenize, yakalamanıza ve istek verilerini değiştirmenize olanak tanır.
  • Mesaj müdahalesi, istek verileriyle ilgili özel mantığı işlemek için en iyi yöntemdir.

Medya yükleniyor

MediaInformation, cast.framework.messages.MessageType.LOAD mesajında medya yüklemek için entity, contentUrl ve contentId dahil olmak üzere çok sayıda özellik sunar.

  • entity, hem gönderen hem de alıcı uygulamalarınız için uygulamanızda kullanılması önerilen özelliktir. Özellik, 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 manifestine işaret edebilir.
  • contentId, 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 parametreleri 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 bulunur ve oynatılabilir contentUrl alınır:

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ı yayın cihazı ve bu cihaza bağlı video veya ses sistemi hakkında cihaz bilgileri sağlar. getDeviceCapabilities yöntemi; Google Asistan, Bluetooth, bağlı ekran ve ses cihazları için destek bilgileri sağlar.

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

Bu örnekte, Web Alıcısı cihazın HDR ve DolbyVision (DV) içerikleri sırasıyla IS_HDR_SUPPORTED ve IS_DV_SUPPORTED anahtarlarıyla oynatıp oynatamayacağı 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 yönetme

Kullanıcılar Web Alıcısı uygulamanızla 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 etkileşim kurabilir. Cast SDK'sı, Web Alıcısı uygulamasının bu etkileşimleri işlemesine, uygulama kullanıcı arayüzünü kullanıcı işlemi durumları aracılığıyla güncellemesine ve isteğe bağlı olarak değişiklikleri arka uç hizmetlerini güncellemek için göndermesine 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ş 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 yönetilir. Mülkte belirli bir bit düzeyinde 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 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üncellenmiş MediaStatus öğesini hazırladığında supportedMediaCommands mülkündeki değişiklikleri içerecektir. 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 kılavuzuna bakın.

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

Kullanıcılar, kullanıcı arayüzüyle etkileşime geçtiklerinde veya sesli komutlar gönderdiklerinde 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. LIKE komutu gibi, oynatılan mevcut öğenin özelliklerini değiştiren isteklerin alıcı uygulama tarafından işlenmesi gerekir. SDK, bu tür istekleri işlemek için bir dizi API sunar. Bu istekleri desteklemek için aşağıdakilerin yapılması gerekir:

  • Bir medya öğesi yüklenirken MediaInformation userActionStates değerini kullanıcının tercihlerine göre ayarlayın.
  • USER_ACTION mesajlarına 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 ucu çağırma işlemini gerçekleştirir. Ardından, alıcıdaki UserActionState değerini güncellemek için bir çağrı 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 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 MediaInformation değerine UserActionState ekler veya bu değerden kaldırır. MediaInformation öğesinin UserActionState değerini güncellemek, istenen işlemle ilişkili düğmenin durumunu değiştirir. 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önderenleri için genişletilmiş kumandanın 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

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

Komut Açıklama
Play Duraklatılmış durumdan oynatmayı başlatma veya devam ettirme
Duraklatma Oynatılmakta olan içeriği duraklatır.
Önceki Medya sıranızdaki önceki medya öğesine atlar.
İleri Medya sıranızdaki bir sonraki medya öğesine atlayın.
Durdur Oynatılmakta olan medyayı durdurun.
Tekrarlama yok Sıradaki son öğenin oynatılması tamamlandıktan sonra sıradaki medya öğelerinin tekrarlanmasını devre dışı bırakın.
Tekrarla Şu anda oynatılan medya içeriğini süresiz olarak tekrarlar.
Tümünü Tekrarla Sıradaki son öğe oynatıldıktan sonra sıradaki tüm öğeleri tekrarlayın.
Tümünü Tekrarla ve Karıştır Sıradaki son öğe oynatıldıktan sonra sırayı karıştırın ve sıradaki tüm öğeleri tekrarlayın.
Karıştır Medya sıranızdaki medya öğelerini karıştırın.
Altyazılar AÇIK/KAPALI Medyanız için altyazıları etkinleştirme/devre dışı bırakma Etkinleştirme/devre dışı bırakma işlemi dile göre de yapılabilir.
Mutlak zamana sar Belirtilen mutlak zamana atlar.
Geçerli zamana göreceli zamana atlama Geçerli oynatma zamanına göre belirtilen süre kadar ileri veya geri atlar.
Tekrar Oyna Şu anda oynatılan medyayı yeniden başlatır veya şu anda hiçbir şey oynatılmıyorsa son oynatılan medya öğesini oynatır.
Oynatma hızını ayarlama Medya oynatma hızını değiştirme Bu işlem varsayılan olarak gerçekleştirilir. Gelen ücret isteklerini geçersiz kılmak için SET_PLAYBACK_RATE mesaj yakalayıcıyı kullanabilirsiniz.

Sesle desteklenen medya komutları

Sesli komutların, 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'sı gönderenlerindeki ve dokunmatik 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ızdan ve dokunmatik 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 listesinde yer almayan tüm gelen sesli komutlar silinir.

Aşağıdaki örnekte, CastReceiverContext başlatılırken CastReceiverOptions sağlanmaktadır. PAUSE komutu için destek ekledik ve oynatıcıyı yalnızca bu komutu destekleyecek şekilde zorunlu kıldık. Artık sesli komutla SEEK gibi başka bir işlem istenirse 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
});

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 mesajı engelleyebilirsiniz. Burada, SDK tarafından sağlanan isteği keserek Asistan özellikli cihazlara verilen SEEK komutlarının Web Alıcısı uygulamanızda arama tetiklemesini önlüyoruz.

Uygulamanızın desteklemediği medya komutları için uygun bir hata nedeni (ör. NOT_SUPPORTED) 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 plana alma

Cast platformu, kullanıcının konuşmasını dinleme veya yanıt verme gibi Asistan etkinliği nedeniyle uygulamanızın sesini arka plana alırsa etkinlik başladığında Web Alıcısı uygulamasına NOT_IN_FOCUS türünde bir 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, FOCUS_STATE mesaj türünü keserek FocusState NOT_IN_FOCUS olduğunda medyayı duraklatmak isteyebilirsiniz.

Örneğin, Asistan bir kullanıcı sorgusuna yanıt verirken 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ı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 önerildiğini veya açıkça istendiğini gösterir.

Örneğin, "Ok Google, altyazıları aç" komutu için isSuggestedLanguage, true olarak ayarlanır. Bunun nedeni, dilin komutun söylendiği dilden anlaşılmasıdır. Dil açıkça istenirse (ör. "Ok Google, İngilizce altyazıları aç"), isSuggestedLanguage false olarak ayarlanır.

Meta veriler ve seslendirme

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

Akış aktarma

Oturum durumunu koruma, akış aktarmanın temelidir. Kullanıcılar sesli komutlar, Google Home uygulaması veya akıllı ekranlar aracılığıyla mevcut ses ve video akışlarını cihazlar arasında taşıyabilir. Medya bir cihazda (kaynak) durur ve başka bir cihazda (hedef) devam eder. En yeni donanım yazılımına sahip tüm Cast cihazları, akış aktarma işleminde kaynak veya hedef olarak kullanılabilir.

Akış aktarma için etkinlik akışı şu şekildedir:

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

Medya durumu öğeleri şunlardır:

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

Akış aktarmayı etkinleştirme

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

  1. supportedMediaCommands dosyasını STREAM_TRANSFER komutuyla güncelleyin: 
    playerManager.addSupportedMediaCommands(
cast.framework.messages.Command.STREAM_TRANSFER, true);
  2. İsterseniz Oturum durumunu koruma bölümünde açıklandığı gibi SESSION_STATE ve RESUME_SESSION mesaj önleyicileri geçersiz kılabilirsiniz. Bu ayarları 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ış aktarmayı destekler.

Oturum durumunu koruma

Web Alıcısı SDK'sı, Web Alıcısı 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.

Web Alıcısı tarafından oluşturulan yükleme isteği, gerekirse 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 mesaj dinleyicisindeki loadRequestData.customData öğesinden 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.

Önceden yükleme işlemi, yaklaşan öğelerin birkaç segmentini önceden indirir. Belirtim, QueueItem nesnesindeki preloadTime değeri üzerinden yapılır (sağlanmazsa varsayılan olarak 20 saniye). Zaman, 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 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. Dolayısıyla, 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, mevcut oynatılan öğenin bant genişliğini ve akış performansını etkileyebileceğinden ayarı ve seçimi geliştiriciye bırakıyoruz.

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

Normal MP4 video ve MP3 gibi ses dosyaları önceden yüklenmez. Bunun nedeni, yayın cihazlarının yalnızca bir medya öğesini desteklemesi ve mevcut bir içerik öğesi oynatılırken önceden yükleme yapmak için kullanılamamasıdır.

Özel mesajlar

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

Gönderen, çalıştığı platformun (Android, iOS, Web) gönderen API'lerini kullanarak Web Alıcısı'na mesaj gönderir. Etkinlik işleyicilere iletilen etkinlik nesnesinin (mesajın somutlaşmış hali) bir veri öğesi (event.data) vardır. Bu öğedeki veriler, belirli etkinlik türünün özelliklerini alır.

Web Alıcısı uygulaması, belirli bir ad alanındaki mesajları dinlemeyi seçebilir. Bu sayede Web Alıcısı uygulamasının, ilgili ad alanı protokolünü desteklediği söylenir. 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şlayıp herhangi bir dizeyle devam etmelidir. Örneğin, "urn:x-cast:com.example.cast.mynamespace".

Bağlı gönderenlerden gelen özel mesajları dinlemek için Web Alıcısı'na yönelik bir 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ısı uygulamaları, bağlı gönderenlere mesaj göndererek gönderenleri Web Alıcısı'nın durumu hakkında bilgilendirebilir. Web Alıcısı uygulaması, CastReceiverContext üzerinde sendCustomMessage(namespace, senderId, message) kullanarak mesaj gönderebilir. Web Alıcısı, 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ıyla) yanı sıra Web Alıcısı, bağlı tüm gönderenlere mesaj da yayınlayabilir.

Ses sistemleri için Cast

Yalnızca ses oynatma desteği için Ses sistemleri 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 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 taşınır 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. Uygulamanız, Android TV'nin kontrol girişlerinden temel oynatma kontrolüne izin vermek için uygulama medya oynatımını kontrol eden bu mesajları desteklemelidir.

Android TV uyumluluğuyla ilgili yönergeler

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

  • 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önlendirebilir. Kullanıcı aracısı dizesindeki "Android" ifadesinin her zaman bir mobil kullanıcıyı gösterdiğini varsaymayın.
  • Android'in medya yığını, veri almak için şeffaf GZIP 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.
  • Medyayı güncellerken <audio>/<video> öğeleri tarafından tetiklenen medyayla ilgili etkinlikleri (ör. timeupdate, pause ve waiting) kullanın. Platforma bağlı olma eğiliminde olduklarından progress, suspend ve stalled gibi ağla ilgili etkinlikleri kullanmaktan kaçının. Alıcınızda 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ını eklediğinizden emin olun. Sitenizin güvenilir sertifika yolunda "ek indirme" etiketli bir CA sertifikası varsa Android tabanlı platformlarda yüklenmeyebilir. Doğrulamak için Qualsys SSL test sayfasına bakın.
  • Chromecast, alıcı sayfasını 720p grafik düzleminde gösterirken Android TV de dahil olmak üzere diğer Cast platformları sayfayı 1080p'ye kadar gösterebilir. Alıcı sayfanızın farklı çözünürlüklerde düzgün şekilde ölçeklendiğinden emin olun.
Önceki
Özel Web Alıcısı
Sonraki
Shaka Oynatıcı Taşıma işleminde HLS