Điểm chèn quảng cáo

Tổng quan

Web receiver SDK hỗ trợ riêng cho các điểm chèn quảng cáo và quảng cáo đồng hành trong một luồng phương tiện truyền thông cụ thể. Cung cấp các API để đặt vị trí quảng cáo, nguồn quảng cáo và hành vi của điểm chèn quảng cáo cũng như các đoạn video chèn quảng cáo có liên quan. Trong hướng dẫn này, Break là khoảng thời gian phát lại có chứa một hoặc nhiều quảng cáo hoặc đoạn quảng cáo đệm và mỗi quảng cáo hoặc đoạn quảng cáo đệm được gọi là BreakClip. Những điểm chèn quảng cáo này liên kết với nội dung nghe nhìn đang được tải hoặc phát.

Loại quảng cáo

Web receiver SDK hỗ trợ tính năng chèn quảng cáo phía máy khách (CSAI) và máy chủ chèn quảng cáo ghép (SSAI). Bạn có thể đặt quảng cáo Do khách hàng ghép theo cách thủ công bằng hoặc được trích xuất từ các tệp mẫu VAST và VMAP. Quảng cáo được máy chủ ghép phải được chỉ định theo cách thủ công trước khi tải nội dung dưới dạng quảng cáo được nhúng hoặc động trong khi phát nội dung dưới dạng được nhúng mở rộng quảng cáo. Cách triển khai cho từng loại quảng cáo này được mô tả chi tiết bên dưới.

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

Các loại dòng thời gian của trình phát

Khi tạo một phiên bản trình phát, SDK Web receiver sẽ chọn một loại dòng thời gian để hỗ trợ phát quảng cáo trong khi phát lại nội dung. Mỗi dòng thời gian sẽ bật một số quảng cáo kiểu ngắt cần thêm. Loại dòng thời gian được xác định theo loại quảng cáo xuất hiện trong thời gian tải trong MediaInformation của LoadRequestData. Nếu có điểm chèn quảng cáo được nhúng, thì dòng thời gian embedded sẽ được chọn. Nếu Có điểm chèn quảng cáo do ứng dụng ghép, dòng thời gian stitched được chọn. Trong trường hợp không có quảng cáo nào, SDK mặc định sẽ sử dụng embedded dòng thời gian. Sau khi chọn dòng thời gian, bạn không thể thay đổi dòng thời gian hiện tại mục nội dung nghe nhìn. Bảng dưới đây mô tả chi tiết về từng tiến trình.

Hình 1 đến 3 dưới đây minh hoạ một số nội dung có nhiều loại quảng cáo và các giá trị dòng thời gian tương ứng. Nội dung được định cấu hình bằng cách chèn trước video có chứa hai đoạn quảng cáo và điểm chèn trong video và sau video có chứa đoạn video chèn quảng cáo. Thời gian theo đồng hồ treo tường kể từ khi bắt đầu phát nội dung, thời gian phát nội dung đa phương tiện của nội dung chính và thời gian quảng cáo hiện là đoạn ngắt phát được căn chỉnh bên dưới mỗi hình.

Định vị điểm chèn

Web receiver SDK cho phép nhà phát triển chỉ định vị trí chèn quảng cáo bằng cách đặt giá trị position của Break. Giá trị này tương ứng với thời gian phát nội dung đa phương tiện của nội dung chính và có thể dùng để tạo điểm chèn quảng cáo pre-roll, mid-roll và post-roll. Các thuộc tính này được xác định như sau:

Ma trận tương tác

Bảng 1 cung cấp thông tin tổng quan về các loại quảng cáo và khả năng tương thích với các tính năng liên quan đến quảng cáo.

Sự kiện

Khi các sự kiện ngắt phím xảy ra, SDK truyền sẽ gửi các sự kiện thuộc loại BreaksEvent. Ứng dụng nhận có thể đăng ký nhận thông báo bằng PlayerManager addEventListener API.

Những sự kiện này có thể được dùng để phân tích và theo dõi lượt phát quảng cáo. Khi VMAP (Danh sách quảng cáo dạng video nhiều quảng cáo) và quảng cáo VAST (Mẫu phân phát quảng cáo dạng video) là thì mọi sự kiện theo dõi chuẩn được cung cấp trong câu trả lời sẽ được tự động do SDK gửi đi.

Loại sự kiện được liệt kê trong Bảng 2 cùng với nội dung mô tả chi tiết về khi chúng được kích hoạt.

Chèn quảng cáo

SDK truyền cho phép ứng dụng chèn và xoá quảng cáo tại nhiều thời điểm của một phiên truyền. Có hai loại chèn quảng cáo là tĩnh và động. Để chèn quảng cáo tĩnh, bạn phải chỉ định quảng cáo trong LoadRequestData trước khi tạo trình phát. Tính năng chèn quảng cáo động sử dụng BreakManager addBreak API để chèn điểm chèn vào nội dung đã tải. Từng kiểu chèn tương thích với một số loại quảng cáo nhất định. Khả năng tương thích thông tin tổng quan được cung cấp trong ma trận khả năng tương tác.

Chèn quảng cáo tĩnh

Chèn quảng cáo tĩnh được đặc trưng bằng cách thêm siêu dữ liệu quảng cáo có liên quan trước đến việc tạo trình phát. Thông tin này có trong MediaInformation trong số LoadRequestData. Ví dụ: bạn có thể đặt giá trị này trong tệp yêu cầu tải ban đầu hoặc có thể được chèn bởi ứng dụng Trình nhận web bằng cách chặn yêu cầu LOAD. Sau khi trả về LoadRequestData Web receiver SDK để xử lý, trình phát sẽ được tạo. Xem thêm trên tải nội dung nghe nhìn. Mẫu bên dưới hiển thị một quảng cáo được ghép bằng ứng dụng thủ công đang được thêm vào yêu cầu LOAD chặn.

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

Chèn quảng cáo động

Đặc điểm của tính năng chèn quảng cáo động là đặt điểm chèn quảng cáo trong nội dung video. Bạn có thể thực hiện việc này bằng cách lấy một thực thể của BreakManager và gọi thời gian addBreak API. Hàm này cần tối thiểu hai tham số, được nhúng đã mở rộng Break và một mảng BreakClip. Thuộc tính thứ ba (không bắt buộc) được đưa vào để buộc gửi các thay đổi tới người gửi được kết nối thông qua thông báo truyền tin MediaStatus khi đặt thành true. Thời gian thêm điểm chèn và chèn đoạn video, thì các mã nhận dạng tương ứng phải là duy nhất. Các quảng cáo này chỉ có thể thêm sau khi tạo trình phát. Web receiver SDK kích hoạt thời gian PLAYER_LOADING sự kiện sau khi tạo người chơi. Hãy xem mẫu dưới đây hiển thị cách sử dụng trong trình xử lý sự kiện phản hồi các thay đổi trong siêu dữ liệu ID3 của một luồng và tạo các đối tượng Break và BreakClip để chèn vào dòng thời gian.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

Xóa quảng cáo động

Để xoá điểm chèn quảng cáo động, ứng dụng cần gọi removeBreakById trong khi phát. Hàm này lấy một giá trị nhận dạng chuỗi của điểm chèn làm giá trị nhận dạng đã bị xóa khỏi dòng thời gian. breakId được chỉ định phải trỏ tới một được nhúng đã mở rộng. Nếu phát hiện thấy bất kỳ loại điểm chèn quảng cáo nào khác, thì điểm chèn này sẽ vẫn có trong tiến trình. Hãy xem mẫu dưới đây để biết cách loại bỏ điểm chèn quảng cáo.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.removeBreakById('break_midroll_embedded_expanded');

Hành vi nghỉ giải lao

SDK xác định hành vi mặc định khi người chơi nhập và rời khỏi đoạn nghỉ giải lao đồng thời cung cấp cách tuỳ chỉnh thêm bằng cách sử dụng một số API được cung cấp inch BreakManager.

Hành vi ngắt mặc định

Khi Break được nhập thông qua chế độ phát thông thường hoặc bằng cách tua qua Break, SDK sẽ đánh giá xem người dùng đã nhìn thấy mã đó hay chưa bằng cách kiểm tra thời gian isWatched thuộc tính này. Khi được tạo, giá trị mặc định của điểm chèn cho thuộc tính này là false. Nếu thuộc tính là true, điểm chèn quảng cáo sẽ không được phát khi vào cửa và chế độ chính nội dung sẽ tiếp tục phát. Nếu giá trị là false, điểm chèn sẽ là được phát khi được nhập.

Khi tìm kiếm các điểm ngắt trong quá khứ, phương thức triển khai mặc định sẽ lấy tất cả Break các mục có position nằm giữa thao tác tìm kiếm seekFrom và seekTo giá trị. Trong danh sách đ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 điểm chèn đó sẽ được đặt thành true và trình phát sẽ bắt đầu phát các đoạn video chèn quảng cáo. Sau khi xem giờ nghỉ, 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 quảng cáo sẽ không được phát và nội dung chính sẽ tiếp tục đang phát ở vị trí seekTo.

Trong khi phát lại quảng cáo, SDK sẽ truyền mọi thông tin cập nhật liên quan đến thiết bị đã kết nối của người gửi trong MediaStatus. Các ứng dụng này sẽ sử dụng thông báo truyền tin để cập nhật giao diện người dùng cho quảng cáo bằng cách đọc thời gian breakStatus thuộc tính này. Thuộc tính này chỉ được xác định trong thời gian phát điểm chèn quảng cáo.

Ứng dụng của dịch vụ nhận cũng có thể truy vấn trực tiếp thông tin liên quan đến vị trí của con trỏ vị trí theo thời gian hiện tại của BreakClip hiển thị bằng cách gọi PlayerManager getBreakClipCurrentTimeSec. Tương tự, các ứng dụng có thể truy vấn khoảng thời gian của BreakClip hiện tại bằng cách đang gọi getBreakClipDurationSec.

Hành vi ngắt tuỳ chỉnh

Hành vi mặc định Bạn có thể điều chỉnh đoạn video chèn quảng cáo bằng cách sử dụng setBreakClipLoadInterceptor và setBreakSeekInterceptor được cung cấp trong BreakManager.

Chặn tìm kiếm ngắt

Trình chặn tìm điểm ngắt cho phép ứng dụng kiểm soát hành vi tua quá nhiều điểm chèn quảng cáo. Hàm này được kích hoạt khi có yêu cầu thực hiện một thao tác tìm kiếm tua đi hoặc tua lại trên một hoặc nhiều điểm ngắt. Khi được gọi, BreakSeekData được truyền dưới dạng tham số vào hàm callback. Đối tượng BreakSeekData chứa một mảng Break các đối tượng có thuộc tính position được đặt thành một số giữa giá trị hiện tại thời gian trên đầu phát được xác định là seekFrom và thời gian đích tìm kiếm seekTo

Trình chặn này cho phép các đối tượng Break trong các điểm ngắt tương ứng được sửa đổi. Khi được triển khai, trình chặn tìm kiếm ngắt phải chỉ định quảng cáo nào ngắt để phát bằng cách trả về một đối tượng BreakSeekData được sửa đổi (không bắt buộc). Chiến lược phát hành đĩa đơn người chơi sẽ tiếp tục chơi tất cả các điểm chèn quảng cáo có trong giá trị trả về. Nếu một giá trị là null hoặc không có giá trị nào được trả về từ trình chặn tìm kiếm điểm chèn, điểm chèn là đã bỏ qua.

Xem mẫu bên dưới để biết cách triển khai đơn giản của trình chặn ghi đè hành vi mặc định để xem tất cả các điểm chèn quảng cáo được tìm kiếm bằng ngoại lệ với những điểm chèn quảng cáo đã xem.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

Chặn trình chặn tải đoạn video

Bằng cách sử dụng trình chặn tải đoạn ngắt, bạn có thể sửa đổi đối tượng BreakClip trước khi bắt đầu phát.

Trình chặn tải đoạn ngắt chỉ được gọi cho dấu ngắt dòng thời gian ghép và có thể thiết lập bằng setBreakClipLoadInterceptor. Trước khi nhập Break, thiết bị chặn này được gọi một lần cho mỗi cá nhân BreakClip được xác định trong điểm chèn đó. SDK truyền phiên bản gốc BreakClip làm tham số của hàm callback. Sau đó, ứng dụng này có thể sửa đổi BreakClip này rồi trả về để SDK có thể tìm nạp và hiển thị điểm chèn với cấu hình đã cập nhật. Nếu giá trị trả về là null hoặc không có giá trị nào được trả về, thì điểm chèn đoạn video bị bỏ qua.

Hãy xem ví dụ dưới đây về cách sửa đổi contentUrl của các đoạn chèn quảng cáo bằng một hàm hiệu dụng sẽ gọi getUrlFromClipId, trong đó id của BreakClip được ánh xạ tới một URL.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

Bỏ qua quảng cáo

Web receiver SDK cung cấp các API để bỏ qua điểm chèn quảng cáo và các đoạn chèn quảng cáo riêng lẻ trong một điểm chèn quảng cáo. SDK cũng cho phép người dùng tuỳ ý bỏ qua các đoạn chèn quảng cáo theo tương tác với các ứng dụng của người gửi hoặc thiết bị hiển thị thông minh.

Đoạn video chèn quảng cáo mà người dùng có thể bỏ qua

Việc đặt các đoạn chèn quảng cáo thành có thể bỏ qua sẽ cho phép người dùng tương tác với người gửi đã kết nối ứng dụng và thiết bị hiển thị thông minh để tuỳ ý bỏ qua phần còn lại của đoạn video chèn quảng cáo hiện đang phát. Thiết lập whenSkippable thành một số giây không âm sẽ bật tính năng này cho Đối tượng BreakClip. Trình phát sẽ coi đoạn video chèn quảng cáo đó có thể bỏ qua sau khi đoạn video chèn quảng cáo đã phát trong số giây đó. Đang đặt giá trị này thành 0 cho phép người dùng bỏ qua đoạn chèn quảng cáo ngay lập tức.

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

Thông tin này có thể được đặt trong yêu cầu tải ban đầu của người gửi hoặc trong nhận. Khi bị bỏ qua, một đoạn chèn quảng cáo trong dòng thời gian ghép sẽ dừng phát đoạn chèn quảng cáo hiện tại. Người chơi sẽ tải ngắt đoạn nếu trình bày hoặc tải nội dung chính. Khi bạn bỏ qua, một đoạn chèn quảng cáo trong Điểm chèn quảng cáo theo dòng thời gian được nhúng sẽ tìm đến cuối đoạn chèn quảng cáo và tiếp tục phát luồng vào thời điểm đó.

Bỏ qua quảng cáo theo phương thức lập trình

Quảng cáo cũng có thể tự động bị bỏ qua mà không cần người dùng phải tương tác.

Để bỏ qua toàn bộ khoảng thời gian nghỉ phát, ứng dụng phải đặt giá trị isWatched từ Break đến true. Bạn có thể thực hiện việc này bất cứ lúc nào trong khi tải trình tự hoặc nội dung. Thuộc tính isWatched được đánh giá bằng trình phát khi gặp position của một điểm chèn quảng cáo trong thời gian hiện tại của nội dung chính. Tại điểm đó, người chơi sẽ xác định xem có nên nhập điểm nghỉ hay không. Xem mẫu bên dưới, vòng lặp thông qua tất cả các điểm chèn và sửa đổi khi trình phát đang tải.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

Để bỏ qua một đoạn video chèn cụ thể theo phương thức lập trình, Bạn nên sử dụng trình chặn tải đoạn quảng cáo ngắt. Theo trả về null hoặc không trả về một giá trị trong hàm callback, sẽ cắt điểm chèn đó sẽ bị bỏ qua.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});