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

Bu sayfa, Özel Web Alıcısı uygulamasında kullanılabilen özelliklerin kod snippet'lerini ve açıklamalarını içerir.

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ü öğelerini biçimlendirmek amacıyla cast-media-player öğesi için CSS benzeri özel stil.
3. Web Recipientr çerçevesini yüklemek için kullanılan bir komut dosyası öğesi.
4. Mesajlara müdahale etmek ve etkinlikleri işlemek için kullanılan JavaScript kodu.
5. Otomatik oynatma için sıraya alın.
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ştiricinin karşılaştığı en dış sınıftır; temel kitaplıkların yüklenmesini ve Web Recipientr SDK'sının başlatılmasını yönetir. Bu SDK, uygulama geliştiricilerin SDK'yı CastReceiverOptions üzerinden yapılandırmasına olanak tanıyan API'ler sağlar. Bu yapılandırmalar, uygulama başlatma 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ı algılamak 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 Uzaktan Hata Ayıklayıcısı oturumunu kapatmasını engelleyeceğinden 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 Recipientr SDK, içerik yüklerken cast.framework.PlaybackConfig kullanarak DRM bilgileri, yeniden deneme yapılandırmaları ve istek işleyicileri gibi oynatma değişkenlerini 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 Alıcı 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 öğesini değiştirmek için aşağıdaki yöntemleri sunar.

• CastReceiverContext başlatılırken varsayılan yapılandırma seçeneklerini geçersiz kılmak için CastReceiverOptions.playbackConfig.
• Mevcut yapılandırmayı almak için PlayerManager.getPlaybackConfig().
• Geçerli yapılandırmayı geçersiz kılmak için PlayerManager.setPlaybackConfig(). Bu ayar sonraki tüm yüklemelere veya tekrar geçersiz kılınana kadar uygulanır.
• Yalnızca mevcut yapılandırmaların üzerine yüklenen medya öğesine ek yapılandırmalar uygulamak için PlayerManager.setMediaPlaybackInfoHandler(). İşleyici, oyuncu 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, CastReceiverContext başlatılırken PlaybackConfig öğesinin nasıl ayarlanacağı gösterilmektedir. Yapılandırma, manifest elde etmek 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 kullanılarak 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ük isteği için PlaybackConfig değerinin nasıl geçersiz kılınacağı gösterilmektedir. İşleyici, licenseUrl değerini geçerli öğenin contentId öğesinden elde etmek için uygulamanın uygulandığı 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 Recipientr SDK, Web Alıcısı uygulamanızın oynatıcı etkinliklerini işlemesini sağlar. 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 konusunda bulabilirsiniz. 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
});

Mesaj müdahalesi

Web Alıcı 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 engelleyici, ne tür bir mesaja müdahale edilmesi gerektiğini belirten bir cast.framework.messages.MessageType parametresi alır.

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

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

      ...

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

Mesaj müdahalesi ve etkinlik işleyici

Mesaj müdahalesi ile etkinlik işleyici arasındaki bazı önemli farklar aşağıda verilmiştir:

• Etkinlik işleyici, istek verilerini değiştirmenize izin vermez.
• Analizleri veya özel bir işlevi tetiklemek için en iyi yöntem etkinlik işleyicidir.

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

• Mesaj müdahalesi, bir mesajı dinlemenize, engellemenize ve istek verilerini değiştirmenize olanak tanır.
• Mesaj müdahalesi, verilerin istenmesiyle ilgili özel mantığı işlemek için kullanılır.

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 sağlar.

• Hem gönderen hem de alıcı uygulamalarınız için uygulamanızda kullanmanız önerilen özelliktir. entity Özellik, bir 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 içerik URL'si (contentUrl özelliğine benzer) veya yüklenen içerik ya da oynatma listesinin benzersiz tanımlayıcısı olabilir. Bu özelliği tanımlayıcı olarak kullanıyorsanız uygulamanızın contentUrl içinde oynatılabilir bir URL'yi doldurması gerekir.

Gerçek kimliği veya anahtar parametrelerini depolamak için entity ve medya URL'si için 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 bilgileri sağlar. getDeviceCapabilities yöntemi; Google Asistan, Bluetooth ile bağlı ekran ve ses cihazları için destek bilgileri sağlar.

Bu yöntem, belirtilen numaralandırma için cihaz özelliklerini almak amacıyla belirtilen numaralandırmalardan 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) oynatma özelliklerini sırasıyla IS_HDR_SUPPORTED ve IS_DV_SUPPORTED 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 yönetme

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 aracılığıyla Web Alıcı uygulamanızla etkileşimde bulunabilir. Cast SDK, 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ını, 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 ayarı belirler. Mülkte belirli bir bit tabanlı Command etkinleştirildiğinde, bu işlemle ilgili düğmeler etkinleştirilir. Değer ayarlanmazsa düğme devre dışı bırakılır. Bu değerler Web Alıcısı'nda şu şekilde değiştirilebilir:

1. Belirli bir Commands öğesini 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 öğesini 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 kılavuzuna bakın.

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

Kullanıcılar kullanıcı arayüzüyle etkileşimde bulunduğunda veya sesli komutlar gönderdiğinde içeriğin oynatılmasını ve oynatılan öğeyle ilgili özellikleri kontrol edebilirler. Oynatmayı kontrol eden istekler, SDK tarafından otomatik olarak işlenir. Oynatılmakta olan öğenin özelliklerini değiştiren istekler (ör. LIKE komutu), alıcı uygulamanın bunları işlemesini gerektirir. SDK, bu tür istekleri ele almak için bir dizi API sağlar. Bu isteklerin desteklenmesi için aşağıdakilerin yapılması gerekir:

• Medya öğesi yüklerken MediaInformation userActionStates özelliğini 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 öğesini güncelleyin.

Aşağıdaki snippet LOAD isteğini engeller ve LoadRequestData MediaInformation URL'sini 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ı engeller ve istenen değişiklikle arka ucun çağrılması işlemini işler. Ardından, alıcıda 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şlemin arka uç tarafından desteklenmesi durumunda 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 öğesinden ekler veya 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üne, uzaktan kumanda uygulamasına 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 iletileri ü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	Oynatmayı duraklatılmış durumda 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.
Tekrar Yok	Sıradaki son öğenin oynatılması tamamlandıktan sonra sıradaki medya öğelerinin tekrarlanmasını devre dışı bırakın.
Bir Tek Tekrarla	Oynatılmakta olan medyayı süresiz olarak tekrarlayın.
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 öğenin çalınması bittiğinde, sırayı karıştırın ve sıradaki tüm öğeleri tekrarlayın.
Karıştırma	Medya sıranızdaki medya öğelerini karıştırın.
Altyazılar AÇIK / KAPALI	Medyanız için Altyazıları etkinleştirin / devre dışı bırakın. Etkinleştirme / Devre dışı bırakma seçenekleri dile göre de sunulur.
Mutlak zamana sar	Belirtilen mutlak zamana atlar.
Geçerli zamana göre sarar	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 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önderenlerdeki ve dokunmatik cihazlardaki kullanıcı arayüzü, bu yapılandırmaları yansıtacak şekilde değişecektir. İşaret etkin değilse gelen sesli komutlar yürütülür.

Örneğin, gönderen uygulamalarınızdan ve dokunma özellikli cihazlarınızdan PAUSE öğesine izin verirseniz alıcınızı da bu ayarları yansıtacak şekilde yapılandırmanız gerekir. Yapılandırıldığında, gelen sesli komutlar desteklenen komutlar listesine dahil değilse 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 desteklemeye zorladık. Artık bir sesli komut SEEK gibi başka bir işlem isterse reddedilir. Kullanıcıya, komutun henüz desteklenmediği konusunda bildirim gönderilir.

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, Asistan özellikli cihazlara verilen SEEK komutlarının Web Alıcısı uygulamanızda arama işlemini tetiklememesi için SDK tarafından sağlanan isteğe müdahale ederiz.

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 etkinlikleri nedeniyle uygulamanızın sesini arka plana atarsa etkinlik başladığında Web Alıcı uygulamasına NOT_IN_FOCUS mesajı gönderilir.FocusState Etkinlik sona erdiğinde IN_FOCUS içeren başka bir ileti 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;
  });

Sesin belirttiği 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 istenip istenmediğini belirtir.

Örneğin, "Ok Google, altyazıları aç" komutu için isSuggestedLanguage dili 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, false olarak ayarlanır.

Meta veri ve ses yayınlama

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ın Asistan tarafından doğru şekilde işlenmesini ve meta verilerin Google Home uygulaması gibi yeni arayüzlerde ve Google Home Hub gibi akıllı ekranlarda düzgün şekilde görünmesini sağlarsınız.

Akış aktarımı

Oturum durumunun korunması, akış aktarımının temelini oluşturur. Burada 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. Medyanın oynatılması durduruluyor.
   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ı, kaydedilen 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) bulunması.
• Kimliği doğrulanmış kullanıcı.
• Oynatma durumu (ör. 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 uygulaması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 önleyicilerini 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 bir parçası olarak depolanması gerekiyorsa geçersiz kılın. Aksi takdirde, oturum durumlarını korumak için varsayılan uygulama akış aktarımını destekler.

Oturum durumu korunuyor

Web Recipientr 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ına varsayılan bir uygulama 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 öğesine 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 müdahale aracındaki 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;
    });

İçeriği önceden yükleme

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

Önceden yükleme işlemi, yaklaşan öğelerin birkaç segmentini önceden indirir. Spesifikasyon, QueueItem nesnesindeki preloadTime değeri üzerinden yapılır (sağlanmazsa varsayılan olarak 20 saniyedir). Süre, o anda oynatılan öğenin sonuna göre saniye cinsinden ifade edilir . Yalnızca pozitif değerler geçerlidir. Örneğin, değer 10 saniyeyse bu öğe, önceki öğe tamamlanmadan 10 saniye önce önceden yüklenir. Önceden yükleme süresi currentItem üzerinde kalan süreden uzunsa önceden yükleme mümkün olan en kısa sürede gerçekleşir. Böylece, rowItem öğesinde çok büyük bir önceden yükleme değeri belirtilirse, mevcut öğeyi her oynattığımızda, bir sonraki öğeyi önceden yüklüyormuşuz gibi bir etki sağlanabilir. Ancak bu değer, geçerli oynatılan öğenin bant genişliğini ve akış performansını etkileyebileceği için ayarı ve 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.

Cast cihazları yalnızca bir medya öğesini desteklediğinden ve mevcut bir içerik öğesi oynatılmaya devam ederken önceden yükleme için kullanılamadığından 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 kullandığı platformun (Android, iOS, Web) gönderen API'lerini kullanarak Web Alıcısına mesaj gönderir. Etkinlik işleyicilere aktarılan 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. Böylece, Web Alıcısı uygulamasının bu ad alanı protokolünü desteklediği söylenir. Daha sonra, uygun protokolü kullanmak bu ad alanı üzerinde iletişim kurmak isteyen tüm bağlı gönderenlere bağlıdır.

Tüm ad alanları bir dizeyle tanımlanır. "urn:x-cast:" ile başlamalı ve ardından herhangi bir dize gelmelidir. Ö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ı, 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) ile mesaj gönderebilir. Web Alıcısı, alınan bir iletiye yanıt olarak veya bir uygulama durumu değişikliği nedeniyle tek bir gönderene mesaj gönderebilir. Bir Web Alıcısı, noktadan noktaya mesajlaşmanın yanı sıra (64 KB sınırıyla) tüm bağlı gönderenlere mesaj yayınlayabilir.

Ses cihazları için yayınlama

Yalnızca ses oynatmayla ilgili destek için Ses cihazları için Google Cast rehberine 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 anlatılmaktadı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. elde kullanılan 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 kuralları

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 görülen hatalar verilmiştir:

• Kullanıcı aracısı dizesinin hem "Android" hem de "CrKey" içerdiğini unutmayın. Bazı siteler "Android" etiketini algıladığı için yalnızca mobil cihazlara yönelik bir siteye yönlendirme yapabilir. Kullanıcı aracısı dizesindeki "Android" ifadesinin 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 için yanıt verebildiğinden emin olun.
• Android TV HTML5 medya etkinlikleri Chromecast'ten farklı zamanlamalarda tetiklenebilir. Bu durum, Chromecast'te gizlenmiş sorunları ortaya çıkarabilir.
• 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 ile ilgili etkinlikleri kullanmaktan kaçının. Bu etkinlikler genellikle platforma bağlıdır. Alıcınızdaki medya etkinliklerini işleme hakkında daha fazla bilgi için Medya etkinlikleri bölümüne bakın.
• Alıcı sitenizin HTTPS sertifikalarını yapılandırırken ara CA sertifikalarını eklediğinizden emin olun. Doğrulamak için Qualsys SSL test sayfasına bakın: Sitenizin güvenilir sertifika yolunda "ek indirme" etiketli bir CA sertifikası varsa Android tabanlı platformlarda yüklenmeyebilir.
• Chromecast, alıcı sayfasını 720p grafik düzleminde görüntülerken, Android TV gibi diğer Yayın platformları ise 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çeklendiğinden emin olun.