adBreak()

Chữ ký hàm:

adBreak(
   type: '<type>',                     // The type of this placement
   name: '<name>',                     // A descriptive name for this placement
   beforeAd: () => {},                 // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                  // Resume the game and re-enable sound
   beforeReward: (showAdFn) => {},     // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},              // Player dismissed the ad before completion
   adViewed: () => {},                 // Ad was viewed and closed
   adBreakDone: (placementInfo) => {}, // Always called (if provided) even if an ad didn't show
);

Tham số adBreak()

Tên Loại Mô tả
Tất cả các loại vị trí
type chuỗi

Loại vị trí. Giá trị:

  • 'preroll' trước khi trò chơi tải (trước khi giao diện người dùng hiển thị)
  • 'start' trước khi bắt đầu chơi (sau khi giao diện người dùng hiển thị)
  • 'pause' người chơi tạm dừng trò chơi
  • 'next' người chơi chuyển sang cấp độ tiếp theo
  • 'browse' người chơi khám phá các lựa chọn bên ngoài lối chơi
  • 'reward' quảng cáo có tặng thưởng
name chuỗi (KHÔNG BẮT BUỘC) tên cho vị trí đặt quảng cáo cụ thể này trong trò chơi của bạn. Đây là một giá trị nhận dạng nội bộ và không hiển thị cho người chơi. Trong các bản phát hành sau này, mã nhận dạng này có thể được dùng để bật các tính năng báo cáo và tối ưu hoá bổ sung.

Bạn nên đặt tên cho tất cả các vị trí của mình.
beforeAd hàm (KHÔNG BẮT BUỘC) Được gọi trước khi quảng cáo hiển thị. Trò chơi sẽ tạm dừng và tắt âm thanh. Bạn phải thực hiện các thao tác này một cách đồng bộ. Quảng cáo sẽ xuất hiện ngay sau khi lệnh gọi lại này kết thúc.
afterAd hàm (KHÔNG BẮT BUỘC) Được gọi sau khi quảng cáo kết thúc (vì bất kỳ lý do nào). Đối với quảng cáo có tặng thưởng, sự kiện này được gọi là after adDismissed hoặc adViewed, tuỳ thuộc vào hành động của người chơi. Bạn nên dùng hàm này để tiếp tục tiến trình trò chơi. Ví dụ: dùng để bật tiếng và bắt đầu cấp độ tiếp theo.
adBreakDone hàm (TUỲ CHỌN) Luôn được gọi là bước cuối cùng trong một adBreak(), ngay cả khi không có quảng cáo nào xuất hiện. Hàm lấy đối số là một đối tượng placementInfo được xác định như sau: 
{
    breakType: '<type>',
    breakName: '<name>',
    breakFormat: 'interstitial|reward',
    breakStatus:  'error|noAdPreloaded|...|viewed',
}
 Hãy xem adBreakDone và placementInfo() để biết nội dung giải thích chi tiết về đối tượng thông tin vị trí.
Chỉ vị trí có tặng thưởng...
beforeReward hàm Được gọi nếu có quảng cáo có tặng thưởng. Hàm này phải nhận một đối số duy nhất – showAdFn(). Bạn phải gọi đối số này để hiển thị quảng cáo có tặng thưởng.
adDismissed hàm Chỉ được gọi cho quảng cáo có tặng thưởng khi người chơi đóng quảng cáo. Phương thức này chỉ được gọi nếu người chơi đóng quảng cáo trước khi quảng cáo phát xong. Trong trường hợp này, bạn không nên trao phần thưởng.
adViewed hàm Chỉ được gọi cho quảng cáo có tặng thưởng khi người chơi xem hết quảng cáo và được cấp phần thưởng.

adBreakDone() and placementInfo

Nếu không có quảng cáo nào để hiển thị, Ad Placement API sẽ không gọi các lệnh gọi lại trước/sau khác nhau mà bạn truyền. Tuy nhiên, nếu bạn cung cấp một lệnh gọi lại adBreakDone(), lệnh gọi lại này sẽ luôn được gọi, ngay cả khi quảng cáo không hiển thị. Điều này cho phép bạn thực hiện mọi công việc bổ sung mà bạn có thể cần thực hiện cho vị trí, chẳng hạn như ghi nhật ký thông tin phân tích bổ sung về vị trí.

Hàm adBreakDone() lấy đối tượng placementInfo làm đối số, được xác định như sau:

{
  breakType: '<type>',
  breakName: '<name>',
  breakFormat: 'interstitial|reward',
  breakStatus: 'notReady|timeout|error|noAdPreloaded|frequencyCapped|ignored|other|dismissed|viewed',
}

Trong đó, các trường trong đối tượng này có ngữ nghĩa như sau:

  • breakType là đối số loại được truyền đến adBreak()
  • breakName là đối số tên được truyền đến adBreak()
  • breakStatus là trạng thái của vị trí này và có thể là một trong các giá trị sau:
breakStatus Lý do
'notReady' API Vị trí đặt quảng cáo chưa được khởi chạy
'timeout' Một vị trí đã hết thời gian chờ vì Ad Placement API mất quá nhiều thời gian để phản hồi
'invalid' Vị trí không hợp lệ và bị bỏ qua – ví dụ: chỉ nên có một vị trí quảng cáo trước video cho mỗi lần tải trang, các quảng cáo trước video tiếp theo sẽ không thành công với trạng thái này
'error' Đã xảy ra lỗi JavaScript trong một lệnh gọi lại
'noAdPreloaded' Quảng cáo chưa được tải trước nên vị trí này đã bị bỏ qua
'frequencyCapped' Quảng cáo không xuất hiện vì giới hạn tần suất được áp dụng cho vị trí này
'ignored' Người dùng không nhấp vào lời nhắc về phần thưởng trước khi họ chuyển sang vị trí tiếp theo, tức là showAdFn() không được gọi trước adBreak() tiếp theo.
'other' Quảng cáo không hiển thị vì một lý do khác. (ví dụ: Quảng cáo vẫn đang được tìm nạp hoặc một quảng cáo được lưu vào bộ nhớ đệm trước đó đã bị loại bỏ vì màn hình được đổi kích thước/xoay.)
'dismissed' Người dùng đã đóng quảng cáo có tặng thưởng trước khi xem hết
'viewed' Người dùng đã xem quảng cáo

Lưu ý: adBreakDone() luôn là lệnh gọi lại cuối cùng mà adBreak() gọi.

Nếu bạn dùng afterAd() để huỷ tạm dừng trò chơi sau khi quảng cáo xuất hiện, thì adBreakDone() sẽ được gọi sau khi trò chơi của bạn khởi động lại. Đối với những việc như ghi nhật ký số liệu phân tích, điều này có thể phù hợp, nhưng nếu bạn muốn thực hiện thêm công việc trước khi trò chơi khởi động lại, hãy di chuyển logic để tạm dừng trò chơi từ afterAd() sang adBreakDone().