پشتیبانی Ad Breaks API را به گیرنده وب اضافه کنید، پشتیبانی API Breaks را به گیرنده وب اضافه کنید

۱. مرور کلی

لوگوی گوگل کست

این آزمایشگاه کد، نحوه ساخت یک برنامه گیرنده وب سفارشی را که از API پخش تبلیغات استفاده می‌کند، شرح می‌دهد.

گوگل کست چیست؟

گوگل کست به کاربران اجازه می‌دهد محتوا را از دستگاه تلفن همراه خود به تلویزیون منتقل کنند. سپس کاربران می‌توانند از دستگاه تلفن همراه خود به عنوان کنترل از راه دور برای پخش رسانه در تلویزیون استفاده کنند.

کیت توسعه نرم‌افزار (SDK) گوگل کست (Google Cast) به شما امکان می‌دهد برنامه خود را برای کنترل تلویزیون یا سیستم صوتی گسترش دهید. کیت توسعه نرم‌افزار کست (Cast SDK) به شما امکان می‌دهد اجزای رابط کاربری لازم را بر اساس چک‌لیست طراحی گوگل کست (Google Cast Design Checklist) اضافه کنید.

چک لیست طراحی گوگل کست (Google Cast) برای استانداردسازی پیاده‌سازی‌های کست ارائه شده است تا تجربیات کاربر در تمام پلتفرم‌های پشتیبانی‌شده، شهودی باشد.

قرار است چه چیزی بسازیم؟

وقتی این آزمایشگاه کد را تکمیل کردید، یک گیرنده‌ی پخش (Cast Receiver) ساخته‌اید که از Break API بهره می‌برد.

آنچه یاد خواهید گرفت

  • نحوه گنجاندن وقفه‌های VMAP و VAST در محتوا برای Cast
  • چگونه از کلیپ‌های استراحت صرف نظر کنیم
  • نحوه سفارشی‌سازی رفتار پیش‌فرض break در جستجو

آنچه نیاز دارید

تجربه

قبل از ادامه‌ی این کدلاگ، مطمئن شوید که تجربه‌ی زیر را دارید.

  • دانش عمومی توسعه وب.
  • ساخت برنامه‌های گیرنده وب Cast.

چگونه از این آموزش استفاده خواهید کرد؟

فقط تا انتها بخوانید آن را بخوانید و تمرین‌ها را انجام دهید

تجربه خود را در ساخت برنامه‌های وب چگونه ارزیابی می‌کنید؟

تازه کار متوسط ماهر

۲. کد نمونه را دریافت کنید

تمام کدهای نمونه را روی رایانه خود دانلود کنید...

و فایل زیپ دانلود شده را از حالت فشرده خارج کنید.

۳. گیرنده را به صورت محلی مستقر کنید

برای اینکه بتوانید از گیرنده وب خود با دستگاه Cast استفاده کنید، باید آن را در جایی میزبانی کنید که دستگاه Cast شما بتواند به آن دسترسی داشته باشد. اگر از قبل سروری دارید که از https پشتیبانی می‌کند، دستورالعمل‌های زیر را رد کنید و URL را یادداشت کنید ، زیرا در بخش بعدی به آن نیاز خواهید داشت.

اگر سروری برای استفاده در دسترس ندارید، می‌توانید از Firebase Hosting یا ngrok استفاده کنید.

سرور را اجرا کنید

پس از تنظیم سرویس مورد نظر خود، به app-start بروید و سرور خود را شروع کنید.

آدرس اینترنتی (URL) گیرنده میزبان خود را یادداشت کنید. در بخش بعدی از آن استفاده خواهید کرد.

۴. یک برنامه را در کنسول توسعه‌دهندگان Cast ثبت کنید

برای اینکه بتوانید یک گیرنده سفارشی، همانطور که در این codelab تعبیه شده است، را روی دستگاه‌های Chromecast اجرا کنید، باید برنامه خود را ثبت کنید . پس از ثبت برنامه، یک شناسه برنامه ایجاد می‌شود که برنامه فرستنده باید برای راه‌اندازی برنامه گیرنده وب پیکربندی شود.

تصویر کنسول توسعه‌دهندگان SDK گوگل کست با دکمه «افزودن برنامه جدید» هایلایت شده

روی «افزودن برنامه جدید» کلیک کنید

تصویر صفحه «برنامه گیرنده جدید» با گزینه «گیرنده سفارشی» هایلایت شده

«گیرنده سفارشی» را انتخاب کنید، این چیزی است که ما در حال ساخت آن هستیم.

تصویر صفحه «گیرنده سفارشی جدید» که نشانی اینترنتی (URL) را نشان می‌دهد که شخصی در حال تایپ آن در فیلد «نشانی اینترنتی برنامه گیرنده» است

جزئیات گیرنده جدید خود را وارد کنید. حتماً از URL ای استفاده کنید که به محلی که قصد میزبانی برنامه گیرنده وب خود را دارید اشاره کند. شناسه برنامه تولید شده توسط کنسول را پس از ثبت برنامه یادداشت کنید . برنامه فرستنده در بخش بعدی برای استفاده از آن شناسه پیکربندی خواهد شد.

همچنین باید یک دستگاه Google Cast ثبت کنید تا قبل از انتشار، بتواند به برنامه گیرنده شما دسترسی داشته باشد. پس از انتشار برنامه گیرنده، برای همه دستگاه‌های Google Cast در دسترس خواهد بود. برای اهداف این آزمایشگاه کد، توصیه می‌شود با یک برنامه گیرنده منتشر نشده کار کنید.

تصویر کنسول توسعه‌دهندگان SDK گوگل کست با دکمه «افزودن دستگاه جدید» هایلایت شده

روی «افزودن دستگاه جدید» کلیک کنید

تصویر پنجره‌ی «افزودن دستگاه گیرنده‌ی پخش»

شماره سریال چاپ شده در پشت دستگاه Cast خود را وارد کنید و یک نام توصیفی به آن بدهید. همچنین می‌توانید با استفاده از Cast کردن صفحه نمایش خود در Chrome هنگام دسترسی به کنسول توسعه‌دهندگان Google Cast SDK، شماره سریال خود را پیدا کنید.

۵ تا ۱۵ دقیقه طول می‌کشد تا گیرنده و دستگاه شما برای آزمایش آماده شوند. پس از ۵ تا ۱۵ دقیقه انتظار، باید دستگاه Cast خود را مجدداً راه‌اندازی کنید.

۵. پروژه شروع را آماده کنید

قبل از شروع این آزمایشگاه کد، ممکن است مرور راهنمای توسعه‌دهنده تبلیغات که مروری بر APIهای مربوط به تبلیغات را ارائه می‌دهد، مفید باشد.

پشتیبانی از گوگل کست باید به برنامه‌ی شروعی که دانلود کرده‌اید اضافه شود. در اینجا برخی از اصطلاحات گوگل کست که در این آزمایشگاه کد استفاده می‌شوند، آورده شده است:

  • یک برنامه فرستنده روی دستگاه تلفن همراه یا لپ‌تاپ اجرا می‌شود،
  • یک برنامه گیرنده روی دستگاه Google Cast اجرا می‌شود.

اکنون آماده‌اید تا با استفاده از ویرایشگر متن مورد علاقه‌تان، پروژه‌ی اولیه را توسعه دهید:

  1. انتخاب کنید آیکون پوشه پوشه app-start از کد نمونه‌ای که دانلود کرده‌اید.
  2. js/receiver.js و index.html را باز کنید.

توجه داشته باشید، همانطور که در حال کار بر روی این آزمایشگاه کد هستید، راهکار میزبانی وب انتخابی شما باید با تغییرات ایجاد شده به‌روز شود. هنگام ادامه اعتبارسنجی و آزمایش تغییرات، مطمئن شوید که آنها را به سایت میزبان اعمال می‌کنید.

طراحی اپلیکیشن

همانطور که گفته شد، codelab از یک برنامه فرستنده برای شروع یک جلسه ارسال (Cast Session) و یک برنامه گیرنده که برای استفاده از APIهای مربوط به اعلان‌های تبلیغاتی اصلاح خواهد شد، استفاده می‌کند.

در این آزمایشگاه کد، ابزار Cast and Command به عنوان فرستنده وب برای اجرای برنامه گیرنده عمل می‌کند. برای شروع، ابزار را در مرورگر کروم باز کنید. شناسه برنامه گیرنده که در کنسول توسعه‌دهندگان Cast SDK به شما داده شده است را وارد کنید و روی Set کلیک کنید تا برنامه فرستنده برای آزمایش پیکربندی شود.

توجه: اگر متوجه شدید که نماد ارسال نمایش داده نمی‌شود، مطمئن شوید که گیرنده وب و دستگاه(های) ارسال به درستی در کنسول توسعه‌دهنده ارسال ثبت شده‌اند. اگر قبلاً این کار را نکرده‌اید، هر دستگاه ارسالی را که تازه ثبت شده‌اند، روشن/خاموش کنید.

تمرکز اصلی این آزمایشگاه کد، روی اپلیکیشن گیرنده است و از یک نمای اصلی تعریف شده در index.html و یک فایل جاوا اسکریپت به نام js/receiver.js تشکیل شده است. این موارد در ادامه بیشتر توضیح داده شده‌اند.

فهرست.html

این فایل html شامل رابط کاربری برنامه گیرنده ما است که توسط عنصر cast-media-player ارائه می‌شود. همچنین کتابخانه‌های CAF SDK و Cast Debug Logger را بارگذاری می‌کند.

گیرنده.js

این اسکریپت تمام منطق برنامه گیرنده ما را مدیریت می‌کند. در حال حاضر، این اسکریپت شامل یک گیرنده CAF پایه برای مقداردهی اولیه زمینه پخش و بارگذاری یک فایل ویدیویی پس از مقداردهی اولیه است. برخی از قابلیت‌های ثبت اشکال‌زدایی نیز برای ارائه گزارش به ابزار پخش و فرمان اضافه شده است.

۶. VMAP را به محتوای خود اضافه کنید

کیت توسعه نرم‌افزاری گیرنده وب کست (Cast Web Receiver SDK) از تبلیغاتی که از طریق فهرست‌های پخش چندگانه تبلیغات دیجیتال ویدیو (Digital Video Multiple Ad Playlists) که با نام VMAP نیز شناخته می‌شود، مشخص می‌شوند، پشتیبانی می‌کند. ساختار XML، وقفه‌های تبلیغاتی یک رسانه و فراداده‌های مربوط به وقفه کلیپ آن را مشخص می‌کند. برای درج این تبلیغات، SDK ویژگی vmapAdsRequest را در شیء MediaInformation ارائه می‌دهد.

در فایل js/receiver.js ، یک شیء VastAdsRequest ایجاد کنید. تابع رهگیری درخواست LOAD را پیدا کرده و آن را با کد زیر جایگزین کنید. این کد شامل یک URL نمونه تگ VMAP از DoubleClick است و یک مقدار همبستگی تصادفی ارائه می‌دهد تا اطمینان حاصل شود که درخواست‌های بعدی به همان URL، یک الگوی XML با تبلیغات موقت ایجاد می‌کنند که هنوز مشاهده نشده‌اند.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      const vmapUrl =
          'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
          Math.floor(Math.random() * Math.pow(10, 10));
      let vmapRequest = new cast.framework.messages.VastAdsRequest();
      vmapRequest.adTagUrl = vmapUrl;
      loadRequestData.media.vmapAdsRequest = vmapRequest;

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

تغییرات خود را در js/receiver.js ذخیره کنید و فایل را در وب سرور خود آپلود کنید. با کلیک بر روی آیکون Cast ، یک جلسه Cast را در ابزار Cast and Command آغاز کنید. تبلیغات VMAP باید پخش شوند و پس از آن محتوای اصلی نمایش داده شود.

۷. به محتوای خود VAST اضافه کنید

همانطور که قبلاً ذکر شد، در SDK گیرنده وب، از انواع مختلفی از تبلیغات پشتیبانی می‌شود. این بخش، APIهای موجود برای ادغام تبلیغات الگوی ارائه تبلیغات ویدیویی دیجیتال که با نام VAST نیز شناخته می‌شود را برجسته می‌کند. اگر کد VMAP را از بخش قبلی پیاده‌سازی کرده‌اید، آن را کامنت کنید.

کد زیر را در فایل js/receiver.js خود، بعد از درخواست بارگذاری interceptor، کپی کنید. این کد شامل شش کلیپ break از VAST از DoubleClick و یک مقدار correlator تصادفی است. این کلیپ‌های break به ۵ break اختصاص داده شده‌اند. position هر break نسبت به محتوای اصلی، بر اساس زمان بر حسب ثانیه تنظیم شده است، که شامل breakهای pre-roll ( position روی 0 تنظیم شده) و post-roll ( position روی -1 تنظیم شده) می‌شود.

const addVASTBreaksToMedia = (mediaInformation) => {
  mediaInformation.breakClips = [
    {
      id: 'bc1',
      title: 'bc1 (Pre-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('preroll')
      }
    },
    {
      id: 'bc2',
      title: 'bc2 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc3',
      title: 'bc3 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc4',
      title: 'bc4 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc5',
      title: 'bc5 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc6',
      title: 'bc6 (Post-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('postroll')
      }
    }
  ];

  mediaInformation.breaks = [
    {id: 'b1', breakClipIds: ['bc1'], position: 0},
    {id: 'b2', breakClipIds: ['bc2'], position: 15},
    {id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
    {id: 'b4', breakClipIds: ['bc5'], position: 100},
    {id: 'b5', breakClipIds: ['bc6'], position: -1}
  ];
};

نکته: ویژگی breakClipIds مربوط به یک break یک آرایه است، به این معنی که می‌توان چندین کلیپ break را به هر break اختصاص داد.

در js/receiver.js file خود، رهگیر پیام LOAD را پیدا کرده و آن را با کد زیر جایگزین کنید. توجه داشته باشید که کار VMAP برای نمایش تبلیغات از نوع VAST به صورت کامنت درآمده است.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      // const vmapUrl =
      //     'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
      //     Math.floor(Math.random() * Math.pow(10, 10));
      // let vmapRequest = new cast.framework.messages.VastAdsRequest();
      // vmapRequest.adTagUrl = vmapUrl;
      // loadRequestData.media.vmapAdsRequest = vmapRequest;

      // Append VAST ad breaks to the MediaInformation.
      addVASTBreaksToMedia(loadRequestData.media);

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

تغییرات خود را در js/receiver.js ذخیره کنید و فایل را در وب سرور خود آپلود کنید. با کلیک بر روی آیکون Cast ، یک جلسه Cast را در ابزار Cast and Command آغاز کنید. تبلیغات VAST و به دنبال آن محتوای اصلی باید پخش شوند.

۸. رد کردن تبلیغات مزاحم

CAF کلاسی به نام BreakManager دارد که به شما در پیاده‌سازی قوانین تجاری سفارشی برای رفتارهای تبلیغاتی کمک می‌کند. یکی از این ویژگی‌ها به برنامه‌ها اجازه می‌دهد تا به صورت برنامه‌نویسی، وقفه‌ها و کلیپ‌های وقفه را بر اساس برخی شرایط رد کنند. این مثال نشان می‌دهد که چگونه می‌توان از یک وقفه تبلیغاتی که موقعیت آن در 30 ثانیه اول محتوا است، رد شد، اما وقفه‌های پس از پخش را رد نکرد. هنگام استفاده از تبلیغات VAST که در بخش قبلی پیکربندی شده است، 5 وقفه تعریف شده است: 1 وقفه قبل از پخش، 3 وقفه در اواسط پخش (در ثانیه‌های 15، 60 و 100) و در نهایت، یک وقفه پس از پخش. پس از انجام مراحل، فقط وقفه‌های قبل از پخش و اواسط پخش که موقعیت آنها در ثانیه 15 است، رد می‌شوند.

برای انجام این کار، برنامه باید API های موجود از طریق BreakManager را فراخوانی کند تا یک interceptor برای بارگذاری break تنظیم کند. خط زیر را در فایل js/receiver.js خود، بعد از خطوط حاوی متغیرهای context و playerManager کپی کنید تا به نمونه ارجاع داده شود.

const breakManager = playerManager.getBreakManager();

برنامه باید یک رهگیر (interceptor) با قاعده‌ای تنظیم کند که هرگونه وقفه تبلیغاتی (ad break) که قبل از 30 ثانیه رخ می‌دهد را نادیده بگیرد و در عین حال وقفه‌های پس از رول (post-roll break) را در نظر بگیرد (زیرا مقادیر position آنها -1 است). این رهگیر مانند رهگیر LOAD در PlayerManager عمل می‌کند، با این تفاوت که این مورد مخصوص بارگذاری کلیپ‌های وقفه است. این را بعد از رهگیر درخواست LOAD و قبل از تعریف تابع addVASTBreaksToMedia تنظیم کنید.

موارد زیر را در فایل js/receiver.js کپی کنید.

breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
  /**
   * The code will skip playback of break clips if the break position is within
   * the first 30 seconds.
   */
  let breakObj = breakContext.break;
  if (breakObj.position >= 0 && breakObj.position < 30) {
    castDebugLogger.debug(
        'MyAPP.LOG',
        'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
    return null;
  } else {
    return breakClip;
  }
});

نکته: برگرداندن null در اینجا، BreakClip در حال پردازش را نادیده می‌گیرد. اگر یک Break هیچ کلیپ Break تعریف شده‌ای نداشته باشد، خود Break نادیده گرفته می‌شود.

تغییرات خود را در js/receiver.js ذخیره کنید و فایل را در وب سرور خود آپلود کنید. با کلیک بر روی آیکون Cast ، یک جلسه Cast را در ابزار Cast and Command آغاز کنید. تبلیغات VAST باید پردازش شوند. توجه داشته باشید که تبلیغات پیش از پخش و اولین تبلیغات میان‌برنامه‌ای (که position آنها ۱۵ ثانیه است) پخش نمی‌شوند.

۹. سفارشی‌سازی رفتار جستجوی استراحت

هنگام جستجوی وقفه‌های گذشته، پیاده‌سازی پیش‌فرض تمام آیتم‌های Break را که موقعیت آنها بین مقادیر seekFrom و seekTo عملیات جستجو است، دریافت می‌کند. از این لیست وقفه‌ها، SDK آن Break را پخش می‌کند که position آن به مقدار seekTo نزدیک‌تر است و ویژگی isWatched آن روی false تنظیم شده است. سپس ویژگی isWatched آن وقفه روی true تنظیم می‌شود و پخش‌کننده شروع به پخش کلیپ‌های break آن می‌کند. پس از مشاهده وقفه، محتوای اصلی از موقعیت seekTo پخش را از سر می‌گیرد. اگر چنین وقفه‌ای وجود نداشته باشد، هیچ وقفه‌ای پخش نمی‌شود و محتوای اصلی پخش را در موقعیت seekTo از سر می‌گیرد.

برای سفارشی‌سازی اینکه کدام breakها در یک جستجو اجرا شوند، Cast SDK، API setBreakSeekInterceptor را در BreakManager ارائه می‌دهد. هنگامی که یک برنامه منطق سفارشی خود را از طریق آن API ارائه می‌دهد، SDK هر زمان که یک عملیات جستجو روی یک یا چند break انجام شود، آن را فراخوانی می‌کند. تابع callback، شیء‌ای را ارسال می‌کند که شامل تمام breakهای بین موقعیت seekFrom و موقعیت seekTo است. سپس برنامه باید BreakSeekData اصلاح کرده و برگرداند.

برای نشان دادن کاربرد آن، نمونه زیر با در نظر گرفتن تمام وقفه‌های جستجو شده و پخش فقط اولین وقفه‌ای که در جدول زمانی ظاهر می‌شود، رفتار پیش‌فرض را لغو می‌کند.

کد زیر را در فایل js/receiver.js خود، زیر تعریف setBreakClipLoadInterceptor کپی کنید.

breakManager.setBreakSeekInterceptor((breakSeekData) => {
  /**
   * The code will play an unwatched break between the seekFrom and seekTo
   * position. Note: If the position of a break is less than 30 then it will be
   * skipped due to the setBreakClipLoadInterceptor code.
   */
  castDebugLogger.debug(
      'MyAPP.LOG',
      'Break Seek Interceptor processing break ids ' +
          JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));

  // Remove all other breaks except for the first one.
  breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
  return breakSeekData;
});

نکته: اگر تابع مقداری را برنگرداند یا اگر null را برگرداند، هیچ وقفه‌ای اجرا نمی‌شود.

تغییرات خود را در js/receiver.js ذخیره کنید و فایل را در وب سرور خود آپلود کنید. با کلیک بر روی آیکون Cast ، یک جلسه Cast را در ابزار Cast and Command آغاز کنید. تبلیغات VAST باید پردازش شوند. توجه داشته باشید که تبلیغات پیش از پخش و اولین تبلیغات میان‌برنامه‌ای (که position آنها ۱۵ ثانیه است) پخش نمی‌شوند.

صبر کنید تا زمان پخش به ۳۰ ثانیه برسد تا از تمام وقفه‌هایی که توسط break clip load interceptor رد می‌شوند، عبور کند. پس از رسیدن به این زمان، با رفتن به تب Media Control ، یک دستور جستجو (seek) ارسال کنید. ورودی Seek Into Media را با 300 ثانیه پر کنید و روی دکمه TO کلیک کنید. به گزارش‌های چاپ شده در Break Seek Interceptor توجه کنید. اکنون باید رفتار پیش‌فرض لغو شود تا وقفه نزدیک‌تر به زمان seekFrom پخش شود.

۱۰. تبریک

اکنون می‌دانید که چگونه با استفاده از جدیدترین SDK گیرنده Cast، تبلیغات را به برنامه گیرنده خود اضافه کنید.

برای جزئیات بیشتر، به راهنمای توسعه‌دهندگان Ad Breaks مراجعه کنید.