Thêm tính năng hỗ trợ API điểm chèn quảng cáo vào trình thu nhận web

1. Tổng quan

Biểu trưng Google Cast

Lớp học lập trình này trình bày cách tạo một ứng dụng Custom Web Receiver sử dụng Cast Ad Breaks API.

Google Cast là gì?

Google Cast cho phép người dùng truyền nội dung từ thiết bị di động lên TV. Sau đó, người dùng có thể dùng thiết bị di động làm điều khiển từ xa để phát nội dung nghe nhìn trên TV.

Google Cast SDK giúp bạn mở rộng ứng dụng để điều khiển TV hoặc hệ thống âm thanh. Cast SDK cho phép bạn thêm các thành phần giao diện người dùng cần thiết dựa trên Danh sách kiểm tra thiết kế của Google Cast.

Danh sách kiểm tra thiết kế Google Cast được cung cấp để chuẩn hoá việc triển khai Cast nhằm mang lại trải nghiệm trực quan cho người dùng trên tất cả các nền tảng được hỗ trợ.

Chúng ta sẽ xây dựng những gì?

Khi hoàn tất lớp học lập trình này, bạn sẽ tạo được một Cast Receiver tận dụng Break API.

Kiến thức bạn sẽ học được

Cách thêm các điểm chèn VMAP và VAST vào nội dung để truyền
Cách bỏ qua đoạn quảng cáo chèn
Cách tuỳ chỉnh hành vi mặc định của điểm ngắt khi tua

Bạn cần có

Trình duyệt Google Chrome mới nhất.
Dịch vụ lưu trữ HTTPS, chẳng hạn như Lưu trữ Firebase hoặc ngrok.
Một thiết bị Google Cast, chẳng hạn như Chromecast hoặc Android TV được thiết lập để có quyền truy cập vào Internet.
TV hoặc màn hình có cổng đầu vào HDMI, hoặc Google Home Hub

Trải nghiệm

Đảm bảo bạn có kinh nghiệm sau đây trước khi tiếp tục tham gia lớp học lập trình này.

Kiến thức chung về phát triển web.
Xây dựng ứng dụng Web Receiver của Cast.

Bạn sẽ sử dụng hướng dẫn này như thế nào?

Chỉ đọc

Đọc và hoàn thành bài tập

Bạn đánh giá thế nào về trải nghiệm xây dựng ứng dụng web?

Người mới bắt đầu

Trung cấp

Thành thạo

2. Nhận mã mẫu

Tải tất cả mã mẫu xuống máy tính của bạn...

và giải nén tệp zip đã tải xuống.

3. Triển khai bộ nhận cục bộ

Để có thể sử dụng trình nhận web với một thiết bị truyền, bạn cần lưu trữ trình nhận web ở một nơi mà thiết bị truyền có thể truy cập. Nếu bạn đã có một máy chủ hỗ trợ https, hãy bỏ qua các hướng dẫn sau và ghi lại URL vì bạn sẽ cần URL đó trong phần tiếp theo.

Nếu không có máy chủ để sử dụng, bạn có thể dùng Lưu trữ Firebase hoặc ngrok.

Chạy máy chủ

Sau khi thiết lập dịch vụ bạn chọn, hãy chuyển đến app-start rồi khởi động máy chủ.

Ghi lại URL cho máy thu được lưu trữ. Bạn sẽ sử dụng đối tượng này trong phần tiếp theo.

4. Đăng ký một ứng dụng trong Cast Developer Console

Bạn phải đăng ký ứng dụng để có thể chạy một trình nhận tuỳ chỉnh (như được tạo trong lớp học lập trình này) trên các thiết bị Chromecast. Sau khi bạn đăng ký ứng dụng, một mã ứng dụng sẽ được tạo. Ứng dụng Sender phải được định cấu hình để chạy ứng dụng Web Receiver.

Hình ảnh về Bảng điều khiển dành cho nhà phát triển SDK của Google Cast, trong đó nút "Thêm ứng dụng mới" được đánh dấu

Nhấp vào "Thêm ứng dụng mới"

Hình ảnh màn hình "Ứng dụng nhận mới" có lựa chọn "Trình nhận tuỳ chỉnh" được làm nổi bật

Chọn "Custom Receiver" (Trình nhận tuỳ chỉnh), đây là thành phần mà chúng ta sẽ tạo.

Hình ảnh màn hình "New Custom Receiver" (Trình nhận tuỳ chỉnh mới) cho thấy một URL mà người dùng đang nhập vào trường "Receiver Application URL" (URL ứng dụng nhận)

Nhập thông tin chi tiết về thiết bị nhận mới. Hãy nhớ sử dụng URL trỏ đến nơi bạn dự định lưu trữ ứng dụng Web Receiver. Ghi lại Mã ứng dụng do bảng điều khiển tạo sau khi bạn đăng ký ứng dụng. Ứng dụng người gửi sẽ được định cấu hình để sử dụng giá trị nhận dạng đó trong một phần sau.

Bạn cũng phải đăng ký một thiết bị truyền Google Cast để thiết bị đó có thể truy cập vào ứng dụng nhận trước khi bạn xuất bản ứng dụng. Sau khi bạn phát hành ứng dụng nhận, ứng dụng đó sẽ có trên tất cả các thiết bị Google Cast. Để phục vụ cho mục đích của lớp học lập trình này, bạn nên làm việc với một ứng dụng nhận chưa được xuất bản.

Hình ảnh Bảng điều khiển dành cho nhà phát triển SDK của Google Cast, trong đó nút "Thêm thiết bị mới" được làm nổi bật

Nhấp vào "Thêm thiết bị mới"

Hình ảnh hộp thoại "Thêm thiết bị nhận nội dung truyền"

Nhập số sê-ri in ở mặt sau của thiết bị truyền và đặt tên mô tả cho thiết bị đó. Bạn cũng có thể tìm thấy số sê-ri bằng cách truyền màn hình trong Chrome khi truy cập vào Bảng điều khiển dành cho nhà phát triển SDK của Google Cast

Quá trình chuẩn bị cho hoạt động kiểm thử sẽ mất từ 5 đến 15 phút. Sau khi đợi 5 đến 15 phút, bạn phải khởi động lại thiết bị truyền.

5. Chuẩn bị Dự án khởi đầu

Trước khi bắt đầu lớp học lập trình này, bạn nên xem hướng dẫn dành cho nhà phát triển quảng cáo để nắm được thông tin tổng quan về các API khoảng thời gian quảng cáo.

Bạn cần thêm tính năng hỗ trợ Google Cast vào ứng dụng khởi động mà bạn đã tải xuống. Sau đây là một số thuật ngữ về Google Cast được dùng trong lớp học lập trình này:

ứng dụng người gửi chạy trên thiết bị di động hoặc máy tính xách tay,
ứng dụng receiver chạy trên thiết bị truyền Google Cast.

Giờ đây, bạn đã sẵn sàng xây dựng dựa trên dự án khởi đầu bằng trình chỉnh sửa văn bản mà bạn yêu thích:

Chọn thư mục app-start trong tệp tải mã mẫu xuống.
Mở js/receiver.js và index.html

Xin lưu ý rằng khi bạn thực hiện lớp học lập trình này, giải pháp lưu trữ web mà bạn đã chọn sẽ được cập nhật theo những thay đổi bạn thực hiện. Đảm bảo rằng bạn đang đẩy các thay đổi vào trang web lưu trữ khi tiếp tục xác thực và kiểm thử các thay đổi đó.

Thiết kế ứng dụng

Như đã đề cập, lớp học lập trình này sử dụng một ứng dụng người gửi để bắt đầu một Phiên truyền và một ứng dụng nhận sẽ được sửa đổi để sử dụng các API khoảng thời gian chèn quảng cáo.

Trong lớp học lập trình này, Công cụ Truyền và điều khiển sẽ đóng vai trò là Trình gửi trên web để chạy ứng dụng nhận. Để bắt đầu, hãy mở công cụ này trong trình duyệt Chrome. Nhập Mã ứng dụng nhận mà bạn nhận được trên Play Console dành cho nhà phát triển Cast SDK rồi nhấp vào Đặt để định cấu hình ứng dụng người gửi cho mục đích kiểm thử.

Lưu ý: Nếu bạn thấy biểu tượng truyền không xuất hiện, hãy đảm bảo rằng Web Receiver và(các) thiết bị truyền đã được đăng ký đúng cách trong Cast Developer Console. Nếu bạn chưa làm, hãy tắt rồi bật lại mọi thiết bị truyền vừa được đăng ký.

Ứng dụng nhận là trọng tâm chính của lớp học lập trình này và bao gồm một khung hiển thị chính được xác định trong index.html và một tệp JavaScript có tên là js/receiver.js. Các loại này được mô tả chi tiết hơn ở bên dưới.

index.html

Tệp html này chứa giao diện người dùng cho ứng dụng nhận do phần tử cast-media-player cung cấp. Thư viện này cũng tải các thư viện CAF SDK và Trình ghi nhật ký gỡ lỗi Cast.

receiver.js

Tập lệnh này quản lý mọi logic cho ứng dụng nhận. Hiện tại, tập lệnh này chứa một trình nhận CAF cơ bản để khởi động ngữ cảnh Cast và tải một thành phần video khi khởi động. Chúng tôi cũng đã thêm một số chức năng của trình ghi nhật ký gỡ lỗi để cung cấp nhật ký cho công cụ Truyền và Lệnh.

6. Thêm VMAP vào nội dung của bạn

Cast Web Receiver SDK hỗ trợ những quảng cáo được chỉ định thông qua Danh sách phát nhiều quảng cáo dạng video kỹ thuật số, còn được gọi là VMAP. Cấu trúc XML chỉ định các điểm chèn quảng cáo của nội dung nghe nhìn và siêu dữ liệu về đoạn quảng cáo được liên kết. Để chèn những quảng cáo này, SDK cung cấp thuộc tính vmapAdsRequest trong đối tượng MediaInformation.

Trong tệp js/receiver.js, hãy tạo một đối tượng VastAdsRequest. Tìm hàm LOAD request interceptor (Trình chặn yêu cầu LOAD) rồi thay thế bằng mã sau đây. Thẻ này chứa một URL thẻ VMAP mẫu từ DoubleClick và cung cấp một giá trị correlator ngẫu nhiên để đảm bảo rằng các yêu cầu tiếp theo đến cùng một URL sẽ tạo ra một mẫu XML có các điểm chèn quảng cáo chưa được xem.

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

Lưu các thay đổi vào js/receiver.js rồi tải tệp lên máy chủ web của bạn. Bắt đầu một phiên truyền bằng Công cụ truyền và lệnh bằng cách nhấp vào biểu tượng Truyền. Quảng cáo VMAP sẽ phát, sau đó là nội dung chính.

7. Thêm VAST vào nội dung của bạn

Như đã đề cập trước đó, Web Receiver SDK hỗ trợ nhiều loại quảng cáo. Phần này nêu bật các API có sẵn để tích hợp quảng cáo Mẫu phân phát quảng cáo dạng video kỹ thuật số, còn được gọi là VAST. Nếu bạn đã triển khai mã VMAP từ phần trước, hãy thêm chú thích cho mã đó.

Sao chép phần sau đây vào tệp js/receiver.js sau trình chặn yêu cầu tải. Nó chứa 6 đoạn quảng cáo trong thời gian tạm dừng VAST của DoubleClick và một giá trị correlator ngẫu nhiên. Các đoạn quảng cáo này được chỉ định cho 5 khoảng thời gian quảng cáo. position của mỗi khoảng thời gian nghỉ được đặt thành một thời gian tính bằng giây so với nội dung chính, bao gồm cả quảng cáo chèn trước (position được đặt thành 0) và quảng cáo chèn sau (position được đặt thành -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}
  ];
};

Lưu ý: Thuộc tính breakClipIds của một điểm chèn quảng cáo là một mảng, tức là bạn có thể chỉ định nhiều đoạn quảng cáo chèn vào mỗi điểm chèn quảng cáo.

Trong js/receiver.js file, hãy tìm trình chặn thông báo LOAD rồi thay thế bằng mã sau. Xin lưu ý rằng VMAP được nhận xét để minh hoạ quảng cáo thuộc loại 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;
    });

Lưu các thay đổi vào js/receiver.js rồi tải tệp lên máy chủ web của bạn. Bắt đầu một phiên truyền bằng Công cụ truyền và lệnh bằng cách nhấp vào biểu tượng Truyền. Quảng cáo VAST sẽ phát, sau đó là nội dung chính.

8. Bỏ qua điểm chèn quảng cáo

CAF có một lớp gọi là BreakManager, giúp bạn triển khai các quy tắc kinh doanh tuỳ chỉnh cho hành vi của quảng cáo. Một trong những tính năng này cho phép các ứng dụng bỏ qua các khoảng thời gian và đoạn quảng cáo trong chương trình theo cách có lập trình dựa trên một số điều kiện. Ví dụ này cho thấy cách bỏ qua một điểm chèn quảng cáo có vị trí nằm trong 30 giây đầu tiên của nội dung, nhưng không phải là điểm chèn quảng cáo chèn sau. Khi sử dụng quảng cáo VAST được định cấu hình trong phần trước, có 5 điểm chèn được xác định: 1 quảng cáo chèn trước, 3 quảng cáo chèn giữa (ở 15, 60 và 100 giây) và cuối cùng là 1 quảng cáo chèn sau. Sau khi bạn hoàn tất các bước, chỉ có quảng cáo chèn trước và quảng cáo chèn giữa có vị trí ở 15 giây mới bị bỏ qua.

Để làm như vậy, ứng dụng phải gọi các API có sẵn thông qua BreakManager để đặt một trình chặn cho quá trình tải điểm chèn. Sao chép dòng sau vào tệp js/receiver.js, sau các dòng chứa biến context và playerManager để tham chiếu đến thực thể.

const breakManager = playerManager.getBreakManager();

Ứng dụng phải thiết lập một trình chặn có quy tắc bỏ qua mọi điểm chèn quảng cáo xảy ra trước 30 giây trong khi lưu ý đến mọi điểm chèn quảng cáo chèn sau (vì giá trị position của các điểm chèn này là -1). Trình chặn này hoạt động giống như trình chặn LOAD trên PlayerManager, ngoại trừ trình chặn này dành riêng cho việc tải các đoạn quảng cáo. Đặt giá trị này sau trình chặn yêu cầu LOAD và trước phần khai báo hàm addVASTBreaksToMedia.

Sao chép nội dung sau vào tệp 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;
  }
});

Lưu ý: Việc trả về null ở đây sẽ bỏ qua BreakClip đang được xử lý. Nếu một Break không có đoạn quảng cáo chèn nào được xác định, thì bản thân điểm chèn đó sẽ bị bỏ qua.

Lưu các thay đổi vào js/receiver.js rồi tải tệp lên máy chủ web của bạn. Bắt đầu một phiên truyền bằng Công cụ truyền và lệnh bằng cách nhấp vào biểu tượng Truyền. Quảng cáo VAST phải được xử lý. Xin lưu ý rằng quảng cáo chèn trước và quảng cáo chèn giữa đầu tiên (có position là 15 giây) sẽ không được phát.

9. Tuỳ chỉnh hành vi tìm đến điểm ngắt

Khi tìm kiếm các điểm chèn trước đó, chế độ triển khai mặc định sẽ lấy tất cả các mục Break có vị trí nằm trong khoảng giữa các giá trị seekFrom và seekTo của thao tác tìm kiếm. Từ danh sách các điểm chèn này, SDK sẽ phát Break có position gần nhất với giá trị seekTo và có thuộc tính isWatched được đặt thành false. Sau đó, thuộc tính isWatched của khoảng thời gian chèn quảng cáo đó được đặt thành true và trình phát bắt đầu phát các đoạn quảng cáo trong khoảng thời gian chèn quảng cáo. Sau khi người xem xem xong khoảng thời gian chèn, nội dung chính sẽ tiếp tục phát từ vị trí seekTo. Nếu không có điểm chèn nào như vậy, thì không có điểm chèn nào được phát và nội dung chính sẽ tiếp tục phát ở vị trí seekTo.

Để tuỳ chỉnh những điểm chèn quảng cáo sẽ phát khi người dùng tìm kiếm, Cast SDK cung cấp API setBreakSeekInterceptor trong BreakManager. Khi một ứng dụng cung cấp logic tuỳ chỉnh thông qua API đó, SDK sẽ gọi logic này bất cứ khi nào một thao tác tìm kiếm được thực hiện trên một hoặc nhiều điểm chèn. Hàm callback được truyền một đối tượng chứa tất cả các điểm ngắt giữa vị trí seekFrom và vị trí seekTo. Sau đó, ứng dụng cần sửa đổi và trả về BreakSeekData.

Để minh hoạ cách sử dụng, mẫu dưới đây sẽ ghi đè hành vi mặc định bằng cách lấy tất cả các điểm chèn đã được tua qua và chỉ phát điểm chèn đầu tiên xuất hiện trên dòng thời gian.

Sao chép nội dung sau vào tệp js/receiver.js trong phần định nghĩa của 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;
});

Lưu ý: Nếu hàm không trả về giá trị hoặc nếu hàm trả về null, thì không có điểm chèn nào được phát.

Đợi thời gian phát đạt đến 30 giây để vượt qua tất cả các điểm chèn bị trình chặn tải đoạn quảng cáo chèn bỏ qua. Khi đạt đến điểm cần tìm, hãy gửi lệnh tìm kiếm bằng cách chuyển đến thẻ Điều khiển nội dung nghe nhìn. Điền 300 giây vào đầu vào Seek Into Media (Tua đến vị trí trong nội dung nghe nhìn) rồi nhấp vào nút TO (Đến). Lưu ý nhật ký được in trong Break Seek Interceptor. Hành vi mặc định hiện sẽ bị ghi đè để phát khoảng thời gian chèn quảng cáo gần với thời gian seekFrom hơn.

10. Xin chúc mừng

Giờ đây, bạn đã biết cách thêm quảng cáo vào ứng dụng nhận bằng Cast Receiver SDK mới nhất.

Để biết thêm thông tin chi tiết, hãy xem Hướng dẫn dành cho nhà phát triển về Quảng cáo trong luồng phát.