إضافة الميزات الأساسية إلى مستقبِل الويب المخصّص

تحتوي هذه الصفحة على مقتطفات رمز ووصف للميزات المتاحة تطبيق جهاز استقبال ويب مخصص.

  1. عنصر cast-media-player يمثّل واجهة المستخدم المضمَّنة في المشغّل المتوفّرة مع WebRecipient.
  2. نمط مخصّص يشبه CSS للعنصر cast-media-player لإنشاء أنماط مختلفة عناصر واجهة المستخدم مثل background-image وsplash-image font-family
  3. عنصر نص برمجي لتحميل إطار عمل WebRecipient.
  4. رمز JavaScript لاعتراض الرسائل والتعامل مع الأحداث
  5. قائمة انتظار التشغيل التلقائي.
  6. خيارات تهيئة التشغيل.
  7. خيارات لضبط سياق مستقبل الويب.
  8. خيارات لضبط الأوامر التي يتيحها تطبيق WebRecipient.
  9. طلب JavaScript لبدء تطبيق Web Acceptr

إعدادات التطبيق وخياراته

إعداد التطبيق

تشير رسالة الأشكال البيانية CastReceiverContext هي الفئة الخارجية التي يتعرض لها المطور، وتدير تحميل المكتبات الأساسية ويعالج إعداد حزمة تطوير البرامج (SDK) لجهاز الاستقبال على الويب. حزمة SDK توفّر واجهات برمجة التطبيقات التي تسمح لمطوّري التطبيقات بضبط حزمة تطوير البرامج (SDK) من خلال CastReceiverOptions يتم تقييم عمليات الضبط هذه مرة واحدة لكل عملية تشغيل تطبيق وتمريرها إلى حزمة SDK عند تعيين المعلمة الاختيارية في طلب start

يوضح المثال أدناه كيفية تجاوز السلوك الافتراضي لاكتشاف ما إذا اتصال المرسل لا يزال متصلاً بنشاط. عندما لا يكون لدى مستلم الويب تمكنت من التواصل مع المرسل بالنسبة maxInactivity ثانية، تم إرسال حدث SENDER_DISCONNECTED. الإعدادات أدناه تلغي هذه المهلة. ويمكن أن يكون ذلك مفيدًا عند تصحيح الأخطاء لأنه يمنعها تطبيق "استقبال الويب" من إغلاق جلسة "برنامج تصحيح الأخطاء عن بُعد في Chrome" عند ليس هناك أي مرسلين متصلين في حالة IDLE.

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

إعداد المشغّل

عند تحميل المحتوى، توفّر "حزمة تطوير البرامج (SDK) استلام الويب" طريقة لضبط التشغيل. مثل DRM المعلومات، وإعادة محاولة التكوينات، ومعالجات الطلب باستخدام cast.framework.PlaybackConfig يتم التعامل مع هذه المعلومات من خلال PlayerManager ويتم تقييمه عند إنشاء اللاعبين. تم إنشاء اللاعبين في كل مرة يتم فيها تمرير تحميل جديد إلى حزمة تطوير البرامج (SDK) لجهاز الاستقبال على الويب. التعديلات على يتم تقييم قيمة PlaybackConfig بعد إنشاء اللاعب في المرحلة التالية. تحميل المحتوى. توفر حزمة SDK الطرق التالية لتعديل PlaybackConfig

  • CastReceiverOptions.playbackConfig لإلغاء خيارات التهيئة الافتراضية عند تهيئة CastReceiverContext
  • PlayerManager.getPlaybackConfig() للحصول على الإعدادات الحالية.
  • PlayerManager.setPlaybackConfig() لإلغاء الإعدادات الحالية. يتم تطبيق هذا الإعداد على جميع عمليات التحميل اللاحقة أو إلى أن يتم إلغاؤها مرة أخرى.
  • PlayerManager.setMediaPlaybackInfoHandler() لتطبيق الإعدادات الإضافية فقط على عنصر الوسائط الذي يتم تحميله عليه أعلى الإعدادات الحالية. يتم استدعاء المعالج قبل اللاعب مباشرةً الإنشاء. التغييرات التي يتم إجراؤها هنا ليست دائمة ولا يتم تضمينها في طلبات البحث إلى getPlaybackConfig(). عند تحميل عنصر الوسائط التالي، يستخدم هذا المعالج مرة أخرى.

يوضّح المثال أدناه كيفية ضبط PlaybackConfig عند إعداد CastReceiverContext تلغي الإعدادات الطلبات الصادرة الحصول على البيانات. يحدد المعالج أن طلبات التحكم في الوصول إلى سياسة مشاركة الموارد المتعددة المصادر (CORS) باستخدام بيانات اعتماد مثل ملفات تعريف الارتباط أو عناوين التفويض.

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

يوضّح المثال أدناه كيفية إلغاء PlaybackConfig باستخدام دالة getter. والتعيين المقدم في PlayerManager. يؤدي الإعداد إلى ضبط المشغّل على استئناف تشغيل المحتوى بعد تحميل مقطع واحد

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

يوضح المثال أدناه كيفية تجاهل PlaybackConfig لعملية تحميل معيّنة. عند الطلب باستخدام معالِج معلومات تشغيل الوسائط. يستدعي المعالج تطبيقًا. تم تنفيذ الطريقة getLicenseUrlForMedia للحصول على licenseUrl من العنصر الحالي contentId

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

  return playbackConfig;
});

أداة معالجة الحدث

إنّ حزمة تطوير البرامج (SDK) الخاصة باستقبال الويب تسمح لتطبيق WebRecipient بمعالجة أحداث المشغّل. تشير رسالة الأشكال البيانية أداة معالجة الحدث تأخذ cast.framework.events.EventType (أو مصفوفة من هذه المعلّمات) تحدّد الأحداث التي يجب أن يشغّل المستمع صفائف تم تكوينها مسبقًا يمكن العثور على cast.framework.events.EventType المفيدة لتصحيح الأخطاء في cast.framework.events.category توفّر مَعلمة الحدث معلومات إضافية عن الحدث.

على سبيل المثال، إذا كنت تريد معرفة وقت mediaStatus بث التغيير، يمكنك استخدام المنطق التالي للتعامل مع الحدث:

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

اعتراض الرسالة

تسمح حزمة تطوير برامج الويب لجهاز الاستقبال لتطبيق WebRecipient باعتراض الرسائل وتنفيذ رمز مخصص على هذه الرسائل. يأخذ معترض الرسالة cast.framework.messages.MessageType التي تحدد نوع الرسالة التي ينبغي اعتراضها.

يجب أن يرسل جهة الاعتراض الطلب المعدّل أو الوعد الذي يتم حله بقيمة الطلب المعدلة. لن يؤدي إرجاع null إلى منع استدعاء المعالِج التلقائي للرسائل. راجع تحميل الوسائط لمزيد من التفاصيل.

على سبيل المثال، إذا كنت تريد تغيير بيانات طلب التحميل، يمكنك استخدام طريقة المنطق التالي لاعتراضه وتعديله:

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

خطأ أثناء المعالجة

عند حدوث أخطاء في أداة اعتراض الرسائل، من المفترض أن يعرض تطبيق "استقبال الويب" تطبيق مناسب cast.framework.messages.ErrorType أو cast.framework.messages.ErrorReason

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

الاعتراض على الرسالة مقابل أداة معالجة الأحداث

بعض الاختلافات الرئيسية بين اعتراض الرسالة وأداة استماع الحدث هي التالي:

  • لا تسمح لك أداة معالجة الحدث بتعديل بيانات الطلب.
  • من الأفضل استخدام أداة معالجة الأحداث لتشغيل الإحصاءات أو دالة مخصصة.
playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });
  • يتيح لك اعتراض الرسالة الاستماع إلى رسالة واعتراضها تعديل بيانات الطلب نفسها.
  • من الأفضل استخدام اعتراض الرسائل للتعامل مع المنطق المخصص في ما يتعلق بيانات الطلب.

جارٍ تحميل الوسائط

MediaInformation توفّر خصائص عديدة لتحميل الوسائط في cast.framework.messages.MessageType.LOAD، بما في ذلك entity، contentUrl، وcontentId.

  • entity هو السمة المقترَحة التي يمكن استخدامها في عملية التنفيذ لكلّ من المُرسِل تطبيقات الاستقبال. الموقع هو عنوان URL لرابط صفحة معيّنة في التطبيق يمكن أن يكون قائمة تشغيل. أو محتوى وسائط. يجب أن يحلِّل التطبيق عنوان URL هذا لملء حقل واحد على الأقل من الحقلين الآخرين.
  • contentUrl مع عنوان URL القابل للتشغيل الذي سيستخدمه المشغّل لتحميل المحتوى. على سبيل المثال، يمكن أن يشير عنوان URL هذا إلى بيان DASH.
  • contentId يمكن أن يكون إما عنوان URL لمحتوى قابل للتشغيل (على نحو يشبه عنوان contentUrl ) أو معرّف فريد للمحتوى أو قائمة التشغيل التي يتم تحميلها. في حال استخدام هذه السمة كمعرّف، يجب أن يملأ تطبيقك عنوان URL قابل للتشغيل في contentUrl.

الاقتراح هو استخدام entity لتخزين المعرّف الفعلي أو المعلَمات الأساسية. استخدام contentUrl لعنوان URL للوسائط. وهناك مثال على ذلك في المقتطف التالي حيث يتوفّر entity في طلب LOAD يتم استرداد contentUrl القابل للتشغيل:

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

إمكانيات الجهاز

تشير رسالة الأشكال البيانية getDeviceCapabilities معلومات الجهاز على جهاز البث المتصل والفيديو أو جهاز سماعي متصل بها. توفّر الطريقة getDeviceCapabilities الدعم معلومات حول "مساعد Google" والبلوتوث والعرض والصوت المتصلَين الأجهزة.

تُرجع هذه الطريقة كائنًا يمكنك الاستعلام عنه من خلال تمرير أحد تعدادات محددة للحصول على قدرة الجهاز على هذا التعداد. تُعد التعدادات محددة في cast.framework.system.DeviceCapabilities

يتحقق هذا المثال مما إذا كان جهاز استقبال الويب قادرًا على تشغيل HDR DolbyVision (DV) باستخدام مفتاحَي IS_HDR_SUPPORTED وIS_DV_SUPPORTED على التوالي.

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

التعامل مع تفاعل المستخدم

يمكن لمستخدم التفاعل مع تطبيق "جهاز استقبال الويب" من خلال المُرسِل. تطبيقات (الويب وAndroid وiOS) والطلبات الصوتية المزوّدة بخدمة "مساعد Google" الأجهزة، وعناصر التحكّم باللمس على الشاشات الذكية، وأجهزة التحكّم عن بُعد على Android TV الأجهزة. توفّر حزمة تطوير البرامج (SDK) للإرسال العديد من واجهات برمجة التطبيقات للسماح لتطبيق "جهاز استقبال الويب" التعامل مع هذه التفاعلات، وتحديث واجهة مستخدم التطبيق من خلال حالات إجراءات المستخدم ويمكنك إرسال التغييرات لتعديل أي خدمات خلفية، إذا أردت ذلك.

طلبات الوسائط المتوافقة

تعتمد حالات عناصر تحكم واجهة المستخدم على MediaStatus.supportedMediaCommands لوحدات التحكم الموسّعة وأجهزة الاستقبال ووحدات التحكم عن بُعد التي تعمل على أجهزة iOS وAndroid التطبيقات التي تعمل على الأجهزة التي تعمل باللمس، وتطبيقات الاستقبال على أجهزة Android TV. عندما تم تفعيل Command على مستوى بت معيّن في الخاصية، وهي الأزرار المرتبطة بهذا الإجراء مفعّلة. وإذا لم يتم ضبط القيمة، فإن الزر غير مفعّل. يمكن تغيير هذه القيم على مستقبل الويب من خلال:

  1. استخدام PlayerManager.setSupportedMediaCommands لتعيين Commands
  2. إضافة أمر جديد باستخدام addSupportedMediaCommands
  3. إزالة أمر موجود باستخدام removeSupportedMediaCommands
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

عندما يحضِّر المُستلِم "MediaStatus" المُعدَّل، سيتضمّن البيانات التغييرات في السمة supportedMediaCommands. عندما تكون الحالة التي يتم بثها، ستُعدِّل تطبيقات المُرسِلين الأزرار في واجهة المستخدم وفقًا لذلك.

لمزيد من المعلومات حول أوامر الوسائط المتوافقة والأجهزة التي تعمل باللمس، راجع Accessing UI controls الدليل.

إدارة حالات إجراءات المستخدم

عندما يتفاعل المستخدمون مع واجهة المستخدم أو يرسلون أوامر صوتية، يمكنهم التحكم في تشغيل المحتوى والخصائص ذات الصلة بالعنصر قيد التشغيل. الطلبات التي تتحكم في التشغيل، وتتولى حزمة SDK التعامل معها تلقائيًا. الطلبات التي تعديل خصائص العنصر الحالي قيد التشغيل، مثل أمر LIKE، أن يتعامل تطبيق المُستلِم معها توفر حزمة SDK سلسلة من واجهات برمجة التطبيقات (API) لمعالجة هذه الأنواع من الطلبات. لدعم هذه الطلبات، يُرجى ملاحظة ما يلي: يجب القيام به:

  • ضبط MediaInformation userActionStates مع الإعدادات المفضّلة للمستخدم عند تحميل ملف وسائط.
  • اعتراض رسائل USER_ACTION وتحديد الإجراء المطلوب.
  • يُرجى تحديث UserActionState في MediaInformation لتحديث واجهة المستخدم.

يعترض المقتطف التالي طلب LOAD ويملأ MediaInformation لـ LoadRequestData. في هذه الحالة، يرغب المستخدم في المحتوى الجاري تحميله.

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

يعترض المقتطف التالي الرسالة USER_ACTION ويعالج طلبات الاتصال الواجهة الخلفية بالتغيير المطلوب. ثم تجري اتصالاً لتحديث UserActionState على جهاز الاستقبال.

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

يحاكي المقتطف التالي اتصالاً بخدمة واجهة خلفية. تتحقق الدالة من صحة UserActionRequestData للاطّلاع على نوع التغيير الذي طلبه المستخدم وإجراء اتصال عبر الشبكة فقط إذا كانت الخلفية تدعم الإجراء.

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

يأخذ المقتطف التالي UserActionRequestData وإما يضيف أو لإزالة UserActionState من MediaInformation. تحديث تغيّر UserActionState من MediaInformation حالة الزر الذي مرتبط بالإجراء المطلوب. ينعكس هذا التغيير في التقارير الذكية واجهة مستخدم أدوات التحكّم في الشاشة وتطبيق التحكّم عن بُعد وواجهة مستخدم Android TV من المهم أيضًا يتم البث عبر رسائل MediaStatus الصادرة لتعديل واجهة مستخدم وحدة تحكم موسّعة لمرسلي أجهزة iOS وAndroid.

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

الطلبات الصوتية

تتوفّر أوامر الوسائط التالية حاليًا في حزمة تطوير البرامج (SDK) لجهاز الاستقبال على الويب لما يلي: الأجهزة المزوّدة بخدمة "مساعد Google" عمليات التنفيذ الافتراضية لهذه الأوامر هي تم العثور عليها في cast.framework.PlayerManager

Command الوصف
Play تشغيل أو استئناف التشغيل من حالة الإيقاف المؤقت
إيقاف مؤقت إيقاف المحتوى الذي يتم تشغيله حاليًا مؤقتًا
السابق يمكنك التخطي إلى عنصر الوسائط السابق في قائمة انتظار الوسائط.
التالي يمكنك التخطي إلى عنصر الوسائط التالي في قائمة انتظار الوسائط.
إيقاف لإيقاف الوسائط قيد التشغيل حاليًا.
عدم التكرار لإيقاف تكرار عناصر الوسائط في قائمة الانتظار بعد انتهاء تشغيل آخر عنصر في قائمة الانتظار.
تكرار أغنية واحدة تكرار الوسائط قيد التشغيل حاليًا إلى أجل غير مسمى
تكرار الكل كرر جميع العناصر في قائمة الانتظار بمجرد تشغيل العنصر الأخير في قائمة الانتظار.
تكرار الكل وترتيب أغانيك عشوائيًا بعد انتهاء تشغيل آخر عنصر في قائمة الانتظار، يمكنك ترتيب قائمة الانتظار عشوائيًا وتكرار جميع العناصر في قائمة الانتظار.
ترتيب عشوائي يمكنك ترتيب ملفات الوسائط في قائمة انتظار الوسائط عشوائيًا.
تفعيل أو إيقاف ميزة "الترجمة والشرح" تفعيل أو إيقاف ميزة "الترجمة والشرح" للوسائط تفعيل / إيقاف متاح أيضًا حسب اللغة.
الانتقال إلى الوقت المطلق للانتقال إلى الوقت المطلق المحدد.
الترجيع إلى الوقت بالنسبة إلى الوقت الحالي الانتقال للأمام أو للخلف حسب الفترة الزمنية المحدّدة مقارنةً بوقت التشغيل الحالي
اللعب مرة أخرى يمكنك إعادة تشغيل الوسائط قيد التشغيل حاليًا أو تشغيل آخر عنصر وسائط تم تشغيله إذا لم يتم تشغيل أي منها حاليًا.
ضبط معدل التشغيل تنويع معدل تشغيل الوسائط. ومن المفترض أن يتم التعامل مع هذا بشكل تلقائي. يمكنك استخدام أداة اعتراض الرسائل SET_PLAYBACK_RATE لإلغاء طلبات معدّل الرسائل الواردة.

طلبات الوسائط المتوافقة باستخدام الصوت

لمنع طلب صوتي من تشغيل أمر وسائط على "مساعد Google" جهاز مزوّد، يجب أولاً تعيين طلبات الوسائط المتوافقة التي تخطط لدعمها. بعد ذلك، يجب فرض هذه الأوامر من خلال تفعيل الـ CastReceiverOptions.enforceSupportedCommands الموقع. ستتغير واجهة المستخدم في أجهزة مُرسِلي حزمة تطوير البرامج (SDK) لتقنية Google Cast والأجهزة التي تعمل باللمس إلى تعكس هذه التكوينات. إذا لم تكن العلامة مُفعَّلة، سيتم تشغيل الصوت الوارد. التي سيتم تنفيذها.

على سبيل المثال، في حال السماح بالوصول إلى PAUSE من تطبيقات المُرسِلين الأجهزة التي تعمل باللمس، فيجب عليك أيضًا تهيئة جهاز الاستقبال ليعكس الإعدادات. عند ضبط الإعدادات، سيتم تجاهل أي طلبات صوتية واردة إذا لم يتم ضبطها. في قائمة الأوامر المتوافقة.

في المثال أدناه، نعرض القيمة CastReceiverOptions عند البدء. CastReceiverContext. وقد أضفنا دعمًا للأمر PAUSE وفرضت على المشغل دعم هذا الأمر فقط. الآن، إذا طلب أمر صوتي طلب عملية أخرى مثل SEEK، سيتم رفضه. سيكون المستخدم إلى أن الأمر غير مدعوم حتى الآن.

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

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

ويمكنك تطبيق منطق منفصل لكل أمر تريد تقييده. إزالة علامة enforceSupportedCommands ولكل أمر تريد تنفيذه اعتراض الرسائل الواردة. نعترض هنا الطلب التي توفّرها حزمة تطوير البرامج (SDK) لكي يتم إصدار أوامر SEEK للأجهزة المزوّدة بخدمة "مساعد Google" عدم بدء التقديم/الترجيع في تطبيق WebRecipient.

بالنسبة إلى أوامر الوسائط التي لا يدعمها التطبيق، يمكنك إرجاع ملف سبب الخطأ، مثل NOT_SUPPORTED

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

الخلفية استنادًا إلى النشاط الصوتي

إذا كانت النظام الأساسي للبث يحوّل صوت تطبيقك إلى الخلفية بسبب استخدام "مساعد Google" نشاط مثل الاستماع إلى كلام المستخدم أو الرد عليه، FocusState يتم إرسال رسالة NOT_IN_FOCUS إلى تطبيق "جهاز استقبال الويب" عند بدء النشاط. يتم إرسال رسالة أخرى إلى "IN_FOCUS" عند انتهاء النشاط. اعتمادًا على التطبيق والوسائط التي يتم تشغيلها، قد تحتاج إلى إيقاف الوسائط مؤقتًا عندما تكون قيمة FocusState هي NOT_IN_FOCUS من خلال اعتراض الرسالة النوع FOCUS_STATE.

على سبيل المثال، من المفيد إيقاف تشغيل الكتاب المسموع مؤقتًا إذا كانت يستجيب "مساعد Google" لطلب بحث المستخدم.

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

لغة الشرح المحددة بالصوت

إذا لم يذكر المستخدم لغة الترجمة بشكل صريح، أن تكون اللغة المستخدمة في الترجمة هي اللغة نفسها التي تم بها قول الأمر. في هذه السيناريوهات، isSuggestedLanguage تشير معلمة الرسالة الواردة إلى ما إذا كانت اللغة المرتبطة يقترحها المستخدم أو يطلبها صراحةً.

على سبيل المثال، يتم ضبط isSuggestedLanguage على true للأمر "OK Google، تفعيل الترجمة والشرح" لأنه تم استنتاج اللغة من خلال اللغة ما تم التحدث فيه. إذا تم طلب اللغة بشكل صريح، مثل "OK Google، أريد تفعيل ميزة الشرح باللغة الإنجليزية"، تم ضبط isSuggestedLanguage على false.

البيانات الوصفية والبث الصوتي

على الرغم من أن مستقبل الويب يتعامل تلقائيًا مع الأوامر الصوتية، إلا أنه يجب ضمان أن تكون البيانات الوصفية للمحتوى كاملة ودقيقة يضمن ذلك أن ويتعامل "مساعد Google" مع الطلبات الصوتية بشكل صحيح وأن البيانات الوصفية يظهر بشكل صحيح عبر أنواع جديدة من الواجهات مثل تطبيق Google Home الشاشات الذكية مثل Google Home Hub

نقل البث

يتم الاحتفاظ بحالة الجلسة أساس نقل البث، حيث يمكن للمستخدمين نقل ملفات الصوت والفيديو الحالية على جميع الأجهزة باستخدام الطلبات الصوتية وGoogle Home التطبيقات أو الشاشات الذكية. يتوقف تشغيل الوسائط على أحد الأجهزة (المصدر) ويستمر على جهاز آخر ( الوجهة). يمكن لأي جهاز بث يتضمّن أحدث البرامج الثابتة العمل كمصادر أو وجهات في نقل البث.

في ما يلي تدفُّق الحدث لنقل البث:

  1. على الجهاز المصدر:
    1. يتوقف تشغيل الوسائط.
    2. يتلقّى تطبيق "جهاز استقبال الويب" أمرًا لحفظ الوسائط الحالية الولاية.
    3. إيقاف تشغيل تطبيق WebRecipient.
  2. على جهاز الوجهة:
    1. يتم تحميل تطبيق "جهاز استقبال الويب".
    2. يتلقى تطبيق WebRecipients أمرًا لاستعادة الوسائط المحفوظة الولاية.
    3. يتم استئناف تشغيل الوسائط.

تشمل عناصر حالة الوسائط ما يلي:

  • الموضع المحدّد أو الطابع الزمني للأغنية أو الفيديو أو عنصر الوسائط
  • ويتم وضعه في قائمة انتظار أوسع (مثل قائمة تشغيل أو راديو لفنّان معيّن).
  • المستخدِم الذي تمت مصادقته.
  • حالة التشغيل (مثل التشغيل أو الإيقاف المؤقت)

تفعيل نقل البث

لتنفيذ نقل البث في مستقبل الويب:

  1. تعديل supportedMediaCommands باستخدام الأمر STREAM_TRANSFER: 
    playerManager.addSupportedMediaCommands(
cast.framework.messages.Command.STREAM_TRANSFER, true);
  2. يمكنك إلغاء الرسالتين SESSION_STATE وRESUME_SESSION بشكل اختياري. أجهزة اعتراض كما هو موضح في "الحفاظ على جلسة العمل" الولاية. عدم إلغاء هذه الإعدادات إلا إذا كانت البيانات المخصّصة بحاجة إلى بيانات تخزينه كجزء من لقطة الجلسة. خلاف ذلك، يأتي دور للحفاظ على حالات الجلسة، يتم دعم نقل البث.

الحفاظ على حالة الجلسة

توفّر "حزمة تطوير البرامج (SDK) لاستقبال الويب" تنفيذًا تلقائيًا لتطبيقات "مستقبل الويب" من أجل: حالات الجلسة من خلال أخذ نبذة عن حالة الوسائط الحالية، وتحويل الحالة إلى طلب تحميل، واستئناف الجلسة مع طلب التحميل.

يمكن إلغاء طلب التحميل الذي أنشأه مستقبل الويب في أداة اعتراض رسالة SESSION_STATE إذا لزم الأمر. إذا كنت تريد إضافة بيانات مخصصة في طلب التحميل، نقترح وضعها في loadRequestData.customData

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

يمكن استرداد البيانات المخصّصة من loadRequestData.customData في اعتراض الرسالة RESUME_SESSION.

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

التحميل المُسبق للمحتوى

يتيح جهاز استقبال الويب التحميل المُسبق لملفات الوسائط بعد التشغيل الحالي العنصر في قائمة الانتظار.

تؤدي عملية التحميل المسبق إلى تنزيل عدة أجزاء من العناصر القادمة. يتم وضع المواصفات في preloadTime في الكائن QueueItem (القيمة التلقائية هي 20 ثانية إذا لم يتم توفيرها). يتم التعبير عن الوقت بالثواني، نسبةً إلى نهاية العنصر قيد التشغيل حاليًا . القيم الموجبة فقط هي صالحة. على سبيل المثال، إذا كانت القيمة 10 ثوانٍ، سيتم تحميل هذا العنصر مسبقًا لمدة 10 ثوانٍ. ثوانٍ قبل انتهاء العنصر السابق. في حال كان وقت التحميل المُسبق أكبر الوقت المتبقي في العنصر الحالي، سيحدث التحميل المسبق بمجرد ممكن. لذا، إذا تم تحديد قيمة كبيرة جدًا للتحميل المسبق في ملف playlistItem، فإن قيمة يمكننا تحقيق تأثير عندما نقوم بتشغيل العنصر الحالي الذي التحميل المسبق للعنصر التالي مسبقًا. ومع ذلك، نترك إعداد واختيار هذا التغيير إلى المطوّر لأنّ هذه القيمة قد تؤثّر في معدّل نقل البيانات وأداء البث. العنصر قيد التشغيل الحالي.

تتوافق ميزة التحميل المُسبق مع البث المباشر وفق بروتوكول HTTP (HLS) وDASH وSmooth (السلاسة) تلقائيًا.

لن يتم تحميل ملفات الفيديو والصوت العادية بتنسيق MP4، مثل MP3، مسبقًا بتنسيق Cast فإن الأجهزة تدعم عنصر وسائط واحدًا فقط ولا يمكن استخدامها للتحميل المسبق أثناء المحتوى الحالي لا يزال قيد التشغيل.

الرسائل المخصَّصة

يُعد تبادل الرسائل طريقة التفاعل الرئيسية لتطبيقات مستقبل الويب.

يصدر المرسل رسائل إلى مستقبل الويب باستخدام واجهات برمجة تطبيقات المرسل النظام الأساسي الذي يستخدمه المُرسِل (Android وiOS والويب). كائن الحدث (الذي هو مظهر لرسالة) التي يتم تمريرها إلى مستمعي الحدث عنصر البيانات (event.data) الذي تأخذ فيه البيانات خصائص لنوع حدث معيّن.

قد يختار تطبيق استلام الويب الاستماع إلى الرسائل على جهاز مساحة الاسم. وبموجب هذا الإجراء، يُقال أنّ تطبيق "جهاز استقبال الويب" تتيح بروتوكول مساحة الاسم هذا. يعود الأمر بعد ذلك إلى أي مرسلين متصلين يرغبون في التواصل على مساحة الاسم هذه لاستخدام البروتوكول المناسب.

يتم تحديد جميع مساحات الاسم من خلال سلسلة ويجب أن تبدأ بـ "urn:x-cast:" متبوعة بأي سلسلة. على سبيل المثال: "urn:x-cast:com.example.cast.mynamespace".

إليك مقتطف رمز لكي يتمكن مستقبل الويب من الاستماع إلى الرسائل المخصصة من المرسلون المتصلون:

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

بالمثل، يمكن لتطبيقات "استقبال الويب" إبقاء المُرسِلين على اطّلاع بالحالة مستقبِل الويب من خلال إرسال رسائل إلى المرسلين المتصلين. جهاز استقبال الويب يمكن للتطبيق إرسال رسائل باستخدام sendCustomMessage(namespace, senderId, message) في CastReceiverContext يمكن لمستلم الويب إرسال رسائل إلى مرسل معين، إما ردًا على رسالة مُستلَمة أو بسبب تغيير في حالة التطبيق. أبعد من نقطة البداية المراسلة (بحد أقصى 64 كيلوبايت)، قد يبث مستقبل الويب أيضًا رسائل إلى جميع المرسلين المتصلين.

البث للأجهزة الصوتية

راجِع دليل Google Cast للأجهزة الصوتية للحصول على الدعم بشأن الصوت. التشغيل فقط.

Android TV

يناقش هذا القسم كيفية استخدام جهاز استقبال الويب من Google للإدخالات أثناء تشغيل البيانات، والتوافق مع Android TV

دمج تطبيقك مع وحدة التحكم عن بُعد

جهاز استقبال الويب من Google الذي يعمل على جهاز Android TV يترجم الإدخال من إدخالات التحكّم بالجهاز (أي جهاز التحكّم عن بُعد المحمول باليد) كتشغيل للوسائط تم تحديدها لمساحة الاسم urn:x-cast:com.google.cast.media، على النحو التالي كما هو موضح في رسائل تشغيل الوسائط. أن يدعم التطبيق هذه الرسائل للتحكم في وسائط التطبيق بهدف السماح بالتحكّم بالتشغيل الأساسي من جهاز التحكّم في Android TV المدخلات.

إرشادات التوافق مع Android TV

فيما يلي بعض التوصيات والمخاطر الشائعة التي يجب تجنبها لضمان يتوافق تطبيقك مع Android TV:

  • يُرجى الانتباه إلى أنّ سلسلة وكيل المستخدم تحتوي على كل من "Android" و"CrKey"؛ فقد تعيد بعض المواقع التوجيه إلى موقع للأجهزة الجوّالة فقط لأنها تكتشف "Android" التصنيف. لا تفترض أن "Android" في سلسلة وكيل المستخدم دائمًا تشير إلى مستخدم الهاتف المحمول.
  • قد تستخدم حزمة الوسائط في Android رمز GZIP شفافًا لجلب البيانات. يُرجى التأكد من أنّ: يمكن لبيانات الوسائط أن تستجيب لـ Accept-Encoding: gzip.
  • قد يتم تشغيل أحداث وسائط HTML5 في Android TV في توقيتات مختلفة عن Chromecast، قد يؤدي هذا إلى كشف المشاكل التي كانت مخفية على Chromecast.
  • عند تعديل الوسائط، استخدِم الأحداث ذات الصلة بالوسائط التي تم إطلاقها من قِبل "<audio>/<video>". العناصر، مثل timeupdate وpause وwaiting. تجنب استخدام الاتصال بالشبكات أحداث ذات صلة مثل progress وsuspend وstalled، إذ غالبًا ما تكون يعتمد على النظام الأساسي. الاطّلاع على أحداث الوسائط للحصول على مزيد من المعلومات حول كيفية التعامل مع أحداث الوسائط في المستلِم.
  • عند إعداد شهادات HTTPS للموقع الإلكتروني المستلِم، يُرجى التأكُّد من تضمين شهادات CA المتوسطة. يمكنك الاطّلاع على صفحة اختبار طبقة المقابس الآمنة (SSL) في Qualsys التحقق: إذا كان مسار الشهادة الموثوق بها لموقعك يتضمن مرجعًا تصديقًا شهادة تحمل اسم "تنزيل إضافي"، فقد لا يتم تحميلها على أجهزة Android الأساسية.
  • وفي حين يعرض جهاز Chromecast صفحة جهاز الاستقبال على مستوى رسومات بدقة 720p، هناك يمكن أن تعرض منصات البث، بما في ذلك Android TV، الصفحات بدقة تصل إلى 1080p. التأكد من يتم تغيير حجم صفحة المتلقي بسلاسة بدرجات دقة مختلفة.
السابق
مستقبِل ويب مخصّص
التالي
بروتوكول HLS في عملية نقل مشغّل Shaka