Ö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 Recipientr 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ü öğelerinin stilini belirlemek için cast-media-player öğesi için CSS benzeri özel stil.
  3. Web Alıcı çerçevesini yüklemek için kullanılan komut dosyası öğesi.
  4. Mesajlara müdahale etmek ve etkinlikleri işlemek için JavaScript kodu.
  5. Otomatik oynatma için sıraya geç.
  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 ve Web Receiver SDK'sının başlatılmasını yönetir. 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 lansmanı başına bir kez değerlendirilir ve start çağrısındaki isteğe bağlı parametre ayarlanırken SDK'ya iletilir.

Aşağıdaki örnekte, bir gönderen bağlantısının hâlâ aktif olarak bağlı olup olmadığının belirlenmesi için 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ı geçersiz kılar. Bu, IDLE durumunda hiç bağlı gönderen olmadığında Web Alıcısı uygulamasının Chrome Remote Hata Ayıklayıcı oturumunu kapatmasını engellediği için sorunlarda hata ayıklarken yararlı 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, yapılandırmaları yeniden deneme ve istek işleyicileri gibi oynatma değişkenlerini cast.framework.PlaybackConfig kullanarak yapılandırmak için bir yol sağlar. Bu bilgiler PlayerManager tarafından işlenir ve oynatıcılar oluşturulurken değerlendirilir. Web Receiver SDK'sına her yeni yükleme iletildiğinde oynatıcılar oluşturulur. Oynatıcı oluşturulduktan sonra PlaybackConfig üzerinde yapılan değişiklikler sonraki içerik yüklemesinde değerlendirilir. SDK, PlaybackConfig üzerinde değişiklik yapmak için aşağıdaki yöntemleri sunar.

Aşağıdaki örnekte, CastReceiverContext başlatılırken PlaybackConfig öğesinin nasıl ayarlanacağı gösterilmektedir. Yapılandırma, manifest 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 getter ve setter öğelerini kullanarak PlaybackConfig öğesinin 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 bilgi işleyici kullanılarak belirli bir yükleme isteği için PlaybackConfig öğesinin nasıl geçersiz kılınacağı gösterilmektedir. İşleyici, licenseUrl öğesini geçerli öğenin contentId öğesinden elde etmek için getLicenseUrlForMedia yöntemini uygulayan bir uygulamayı ç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 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 parametrelerden oluşan bir dizi) alır. Hata ayıklama için yararlı olabilecek ö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ı öğ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
});

İletileri müdahale etme

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

Müdahale aracı, değiştirilen istek veya değiştirilen istek değeriyle çözümlenen bir Promise döndürmelidir. null döndürüldüğünde varsayılan mesaj işleyicinin çağrılması engellenir. Daha fazla ayrıntı için Medya yükleme bölümüne bakın.

Örneğin, yükleme isteği verilerini değiştirmek isterseniz verileri engellemek ve 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 engelleyicide hatalar ortaya çıktığında Web Alıcı uygulamanız uygun 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 müdahalesi ve etkinlik işleyici

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

  • Etkinlik işleyici, istek verilerini değiştirmenize izin vermez.
  • Analizleri veya özel bir işlevi tetiklemek için en iyi yöntem bir etkinlik işleyicidir.
playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });
  • Mesaj müdahalesi bir mesajı dinlemenize, müdahale etmenize ve istek verilerini değiştirmenize olanak tanır.
  • Mesaj müdahalesinin, veri isteğinde bulunmayla ilgili özel mantığı işlemek için kullanılması en iyi yöntemdir.

Medya yükleniyor

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

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

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

contentId, değerin medya URL'si, gerçek kimlik veya özel arama için anahtar parametresi olup olmamasıyla ilgili belirsizlik nedeniyle kullanımdan kaldırılmıştır.

Gerçek kimlik veya anahtar parametreleri depolamak için entity, medya URL'si için de contentUrl kullanılması önerilir. Bunun bir örneği, LOAD isteğinde entity öğesinin bulunduğu ve oynatılabilir contentUrl öğesinin alındığı aşağıdaki snippet'te gösterilmiştir:

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

Bu yöntem, belirtilen numaralandırmanın cihaz özelliklerini elde etmek için belirtilen enum'lardan birini geçirerek sorgulayabileceğiniz bir nesne döndürür. Sıralamalar cast.framework.system.DeviceCapabilities içinde tanımlanır.

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

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

Bir kullanıcı; gönderen uygulamaları (Web, Android ve iOS), Asistan özellikli cihazlardaki sesli komutları, akıllı ekranlardaki dokunma kontrolleri ve Android TV cihazlarındaki uzaktan kumandaları kullanarak Web Alıcısı uygulamanızla etkileşimde bulunabilir. Cast SDK'sı, Web Alıcısı uygulamasının bu etkileşimleri işlemesini, uygulama kullanıcı arayüzünü kullanıcı işlemi durumları ile güncellemesini ve isteğe bağlı olarak arka uç hizmetlerini güncellemek için değişiklikleri göndermesini sağlayan çeşitli API'ler sağlar.

Desteklenen medya komutları

Kullanıcı arayüzü kontrolleri 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 aracılığıyla belirlenir. Mülkte belirli bir bit tabanlı Command etkinleştirildiğinde, söz konusu 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 şekilde değiştirilebilir:

  1. Özel Commands özelliğini ayarlamak için PlayerManager.setSupportedMediaCommands kullanma
  2. addSupportedMediaCommands ile yeni bir komut ekleme
  3. removeSupportedMediaCommands kullanarak mevcut bir komutu kaldırma.
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

Alıcı, güncellenen MediaStatus dosyasını hazırladığında supportedMediaCommands özelliğindeki değişiklikler dahil edilir. Durum yayınlandığında, bağlı gönderen uygulamaları kullanıcı arayüzündeki düğmeleri uygun şekilde 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şimde bulunduğunda veya sesli komut gönderdiklerinde, oynatılan öğeyle ilgili içeriğin ve özelliklerin oynatılmasını kontrol edebilirler. Oynatmayı kontrol eden istekler SDK tarafından otomatik olarak işlenir. Oynatılmakta olan öğenin LIKE komutu gibi özelliklerini değiştiren istekler alıcı uygulamanın bunları işlemesini gerektirir. SDK, bu tür istekleri işlemek için bir dizi API sağlar. Bu isteklerin desteklenmesi için aşağıdakiler yapılmalıdır:

  • Medya öğesi yüklerken MediaInformation öğesini userActionStates kullanıcının tercihleriyle ayarlayın.
  • USER_ACTION iletiye müdahale edin ve istenen işlemi belirleyin.
  • Kullanıcı arayüzünü güncellemek için MediaInformation UserActionState uygulamasını güncelleyin.

Aşağıdaki snippet LOAD isteğine müdahale eder ve LoadRequestData MediaInformation parametresini 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ına müdahale eder ve istenen değişiklikle arka ucu çağırma işlemini gerçekleştirir. Ardından, alıcıdaki UserActionState öğesini 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 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 öğesini alır ve UserActionState öğesini MediaInformation öğesine ekler veya buradan kaldırır. MediaInformation öğesinin UserActionState öğesinin güncellenmesi, istenen işlemle ilişkilendirilen düğmenin durumunu değiştirir. Bu değişiklik; akıllı ekran kontrolleri kullanıcı arayüzü, uzaktan kumanda uygulaması ve Android TV kullanıcı arayüzüne yansıtılmıştır. Ayrıca, iOS ve Android gönderenleri için genişletilmiş denetleyicinin kullanıcı arayüzünü güncellemek amacıyla giden MediaStatus mesajları üzerinden yayınlanır.

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

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

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

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

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

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

Sesli komutlar

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

Komut Açıklama
Play Çalmayı duraklatma durumundan oynatın veya devam ettirin.
Duraklat Şu anda oynatılan içeriği duraklatın.
Önceki Medya sıranızdaki önceki medya öğesine atlayın.
İleri Medya sıranızdaki sonraki medya öğesine atlayın.
Durdur Şu anda oynatılan medyayı durdurun.
Hiçbiri Tekrarlama Sıradaki son öğenin oynatılması tamamlandıktan sonra sıradaki medya öğelerinin tekrarlanmasını devre dışı bırak.
Tek Parça Tekrarla Şu anda oynatılan medyayı süresiz olarak tekrarla.
Tümünü Tekrarla Sıradaki son öğe oynatıldığında, sıradaki tüm öğeleri yineleyin.
Tümünü Tekrarla ve Karıştır Sıradaki son öğenin oynatılması tamamlandı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ı özelliğini etkinleştirin / devre dışı bırakın. Etkinleştirme / Devre Dışı Bırakma, dile göre de kullanılabilir.
Mutlak zamana sar Belirtilen mutlak zamana atlar.
Geçerli saate göreli zamana sar. Geçerli oynatma süresine göre, belirtilen dönemde ileri veya geri atlar.
Tekrar Oyna Oynatılmakta olan medyayı yeniden başlatın veya hiçbir şey oynatılmıyorsa son oynatılan medya öğesini oynatın.
Oynatma hızını ayarla Medya oynatma hızını değiştirin. Bu, varsayılan olarak işlenmelidir. Gelen ücret isteklerini geçersiz kılmak için SET_PLAYBACK_RATE mesaj müdahale aracını kullanabilirsiniz.

Sesli desteklenen medya komutları

Sesli komutun Asistan özellikli bir cihazda medya komutu 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önderenlerdeki ve dokunmatik cihazlardaki kullanıcı arayüzü, bu yapılandırmaları yansıtacak şekilde değişecektir. İşaret etkinleştirilmemişse gelen sesli komutlar yürütülür.

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

Aşağıdaki örnekte, CastReceiverContext başlatılırken CastReceiverOptions öğesini sağlıyoruz. PAUSE komutu için destek ekledik ve oynatıcıyı yalnızca bu komutu destekleyecek şekilde zorunlu kıldık. Artık bir sesli komut SEEK gibi başka bir işlem isterse reddedilir. Komutun henüz desteklenmediğine dair kullanıcı bilgilendirilir.

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ı kesebilirsiniz. Burada, Asistan özellikli cihazlara verilen SEEK komutlarının Web Alıcısı uygulamanızda arama tetiklememesi için SDK tarafından sağlanan isteği yakalarız.

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

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

    return seekData;
  });

Ses etkinliğinden arka plan yapma

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 FocusState Web Alıcısı uygulamasına NOT_IN_FOCUS mesajı gönderilir. Etkinlik sona erdiğinde IN_FOCUS içeren 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üne müdahale ederek medyayı duraklatmak isteyebilirsiniz.

Örneğin, Asistan bir kullanıcı sorgusuna yanıt veriyorsa sesli kitap çalmayı 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 konuşulduğu dille aynı olur. Bu senaryolarda gelen mesajın isSuggestedLanguage parametresi, ilişkili dilin kullanıcı tarafından önerilip önerilmediğini veya açıkça istenip istenmediğini belirtir.

Örneğin isSuggestedLanguage, "Ok Google, altyazıları aç" komutu için true olarak ayarlanmıştır çünkü dil, komutun konuşulduğu dile göre belirlenir. Dil açıkça istenirse (ör. "Ok Google, İngilizce altyazıları aç") isSuggestedLanguage ayarı false olarak ayarlanır.

Meta veri ve ses yayınlama

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

Akış aktarma

Oturum durumunun korunması, akış aktarımının temelini oluşturur. Bu aşamada kullanıcılar, mevcut ses ve video akışlarını sesli komutlar, Google Home uygulaması veya akıllı ekranlar kullanarak cihazlar arasında taşıyabilir. Medyanın oynatılması bir cihazda (kaynak) durdurulur ve başka bir cihazda (hedef) devam eder. En yeni donanım yazılımına sahip her yayın cihazı, akış aktarımında kaynak veya hedef olarak kullanılabilir.

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

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

Medya durumu öğeleri şunları içerir:

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

Akış aktarımı etkinleştiriliyor

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

  1. supportedMediaCommands alanını STREAM_TRANSFER komutuyla güncelleyin: 
    playerManager.addSupportedMediaCommands(
cast.framework.messages.Command.STREAM_TRANSFER, true);
  2. İsteğe bağlı olarak SESSION_STATE ve RESUME_SESSION mesaj engelleyicilerini Oturum durumunu koruma bölümünde açıklandığı gibi geçersiz kılın. Bunları yalnızca, özel verilerin oturum anlık görüntüsünün parçası olarak depolanması gerekiyorsa geçersiz kılın. Aksi takdirde, oturum durumlarını korumak için uygulanan varsayılan uygulama, akış aktarımını destekler.

Oturum durumu korunuyor

Web Alıcı SDK'sı, 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ı korumak için Web Alıcısı uygulamalarının varsayılan bir uygulamasını sağlar.

Web Alıcısı tarafından oluşturulan yükleme isteği, gerekirse SESSION_STATE mesaj müdahale aracında geçersiz kılınabilir. Yükleme isteğine özel veriler 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 mesaj müdahale aracındaki loadRequestData.customData adresinden 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;
    });

İçeriği ö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. Spesifikasyon, QueueItem nesnesindeki preloadTime değeri üzerinden yapılır (sağlanmazsa varsayılan olarak 20 saniyedir). Süre, geçerli olarak 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 özelliğinde kalan süreden uzunsa önceden yükleme mümkün olan en kısa sürede gerçekleşir. Böylece, rowItem için çok büyük bir önceden yükleme değeri belirtilirse, mevcut öğe ne zaman oynatıldığında bir sonraki öğe önceden yükleniyormuş gibi bir etki sağlanabilir. Bununla birlikte, bu değer oynatılan öğenin bant genişliğini ve akış performansını etkileyebileceği için ayarı ve bu seçimi geliştiriciye bırakırız.

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

Yayın cihazları yalnızca bir medya öğesini desteklediğinden ve mevcut bir içerik öğesi oynatılırken önceden yükleme yapmak için kullanılamayacaktan MP3 gibi normal MP4 video ve ses dosyaları önceden yüklenmez.

Özel mesajlar

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

Bir gönderen, gönderenin çalıştırdığı platforma (Android, iOS, Web) yönelik gönderen API'lerini kullanarak Web Alıcısı'na mesaj gönderir. Etkinlik işleyicilere iletilen etkinlik nesnesi (bir mesajın manifestidir), verilerin belirli etkinlik türünün özelliklerini aldığı bir veri öğesine (event.data) sahiptir.

Bir Web Alıcısı uygulaması, belirli bir ad alanındaki mesajları dinlemeyi seçebilir. Bu şekilde Web Alıcısı uygulamasının söz konusu ad alanı protokolünü desteklediği söylenir. Bu durumda, uygun protokolü kullanmak için bu ad alanı üzerinde iletişim kurmak isteyen bağlı gönderenlerin sorumluluğundadır.

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

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

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

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

context.start();

Benzer şekilde, Web Alıcısı uygulamaları da bağlı gönderenlere ileti göndererek gönderenleri Web Alıcısı'nın durumu hakkında bilgilendirebilir. Bir Web Alıcısı uygulaması, CastReceiverContext üzerinde sendCustomMessage(namespace, senderId, message) kullanarak mesaj gönderebilir. Web Alıcısı, alınan bir iletiye yanıt olarak veya bir uygulama durumu değişikliği nedeniyle bireysel bir gönderene mesaj gönderebilir. Bir Web Alıcısı, noktadan noktaya mesajlaşmanın (64 kb sınırıyla) yanı sıra, bağlı tüm gönderenlere de mesaj yayınlayabilir.

Ses cihazları için yayınlama

Yalnızca ses oynatma konusunda 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 girişlerinizi oynatma olarak nasıl kullandığı ve Android TV uyumluluğu açıklanmaktadır.

Uygulamanızı uzaktan kumandayla entegre etme

Android TV cihazında çalışan Google Web Alıcısı, Medya Oynatma Mesajları bölümünde açıklandığı gibi cihazın kontrol girişlerinden (ör. uzaktan kumanda) gelen girişleri urn:x-cast:com.google.cast.media ad alanı için tanımlanan medya oynatma mesajları olarak çevirir. Uygulamanızın, Android TV'nin kontrol girişlerinden temel oynatma kontrolüne izin vermesi için medya oynatma işlevini kontrol ederken bu mesajları desteklemesi gerekir.

Android TV uyumluluğu ile ilgili yönergeler

Aşağıda, uygulamanızın Android TV ile uyumlu olmasını sağlamak için kaçınmanız gereken bazı öneriler ve yaygın tuzaklar verilmiştir:

  • Kullanıcı aracısı dizesinin hem "Android" hem de "CrKey"i içerdiğini unutmayın. Bazı siteler "Android" etiketini algıladığı için yalnızca mobil cihazlara yönelik bir siteye yönlendirme yapabilir. Kullanıcı aracısı dizesindeki "Android"in her zaman bir mobil kullanıcıyı belirttiğini varsaymayın.
  • Android'in medya yığını, verileri getirmek için şeffaf GZIP kullanabilir. Medya verilerinizin Accept-Encoding: gzip özelliğine yanıt verebildiğinden emin olun.
  • Android TV HTML5 medya etkinlikleri Chromecast'ten farklı zamanlamalarda tetiklenebilir. Bu durum, Chromecast'te gizlenmiş sorunların ortaya çıkmasına neden olabilir.
  • Medyayı güncellerken timeupdate, pause ve waiting gibi <audio>/<video> öğeleri tarafından tetiklenen medyayla ilgili etkinlikleri kullanın. progress, suspend ve stalled gibi ağ iletişimi etkinlikleri platforma bağlı olduğu için bu etkinlikleri kullanmaktan kaçının. Alıcınızda medya etkinliklerini işleme hakkında daha fazla bilgi için Medya etkinlikleri konusuna bakın.
  • 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 yolunda "extra download" etiketli bir CA sertifikası varsa bu sertifika Android tabanlı platformlarda yüklenmeyebilir.
  • Chromecast, alıcı sayfasını 720p grafik düzleminde görüntülerken, Android TV gibi diğer yayınlama platformları sayfayı 1080p çözünürlüğe kadar görüntüleyebilir. Alıcı sayfanızın farklı çözünürlüklerde sorunsuz bir şekilde ölçeklendirildiğinden emin olun.
Önceki
Özel Web Alıcısı
Sonraki
Shaka Oynatıcı Taşıma işleminde HLS