Sử dụng API Vị trí đặt quảng cáo

API Vị trí đặt quảng cáo chứa hai hàm: adBreak() và adConfig(), được xác định trong vùng chứa tên chung sau đây. Hầu hết các đối số là các hàm bạn cung cấp cho phép bạn xử lý các bước chính để chuẩn bị và hiển thị quảng cáo:

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 un-mute the 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
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

Các hàm này dùng để đặt và định cấu hình quảng cáo trong trò chơi của bạn. Các đối số ở trên là các đối số hợp lệ duy nhất có thể được truyền đến các hàm này. Các loại quảng cáo khác nhau yêu cầu các tập hợp con khác nhau trong số các đối số này như được nêu chi tiết bên dưới.

adBreak() là chức năng chính để đặt quảng cáo trong trò chơi của bạn. Quy trình này xác định vị trí đặt quảng cáo và lấy đối tượng có tên là cấu hình vị trí chỉ định mọi thứ cần thiết để hiển thị quảng cáo.

Hàm adBreak() xác định một vị trí mà quảng cáo có thể hiển thị. Việc một quảng cáo có thực sự xuất hiện hay không phụ thuộc vào những yếu tố như sau:

  • Loại vị trí đặt quảng cáo mà bạn đã khai báo
    • Quảng cáo này có xuất hiện ở đầu trò chơi không? Giữa các cấp? Vào thời điểm người chơi đã tạm dừng trò chơi?
  • Có quảng cáo phù hợp cho người chơi hiện tại hay không
    • Quảng cáo này có phù hợp với họ không?
    • Việc này có nhất quán với chế độ cài đặt về quyền riêng tư và sự đồng ý của người dùng không?
  • Số lượng quảng cáo mà người chơi thấy gần đây
  • Chế độ cài đặt kiểm soát (ví dụ: tần suất quảng cáo mà bạn đã thiết lập cho trò chơi này)
    • Làm gợi ý trong thẻ hoặc
    • Trong AdSense – lưu ý rằng các chế độ kiểm soát hiện có trong AdSense sẽ phát triển theo thời gian.

Loại quảng cáo xuất hiện cũng phụ thuộc vào các yếu tố tương tự.

Xin lưu ý rằng lệnh gọi đến adBreak() hoàn toàn không thể hiển thị quảng cáo. Danh sách này chỉ khai báo nơi mà quảng cáo có thể hiển thị.

Khác với các API truyền thống, trong đó mã của bạn luôn biết có quảng cáo hay không, và bạn quyết định có hiển thị quảng cáo trong trò chơi hay không. Phương pháp để API Vị trí đặt quảng cáo này quyết định liệu một quảng cáo có xuất hiện ở một vị trí cụ thể hay không là một mẫu đôi khi được gọi là "đảo ngược quyền kiểm soát".

Lý do chúng tôi chuyển đổi API trò chơi sang mô hình này trước tiên là để rút ngắn mã bạn phải viết trong trò chơi của mình. Thứ hai, việc này giúp dễ dàng phân phối các vị trí tuân thủ chính sách với trải nghiệm người dùng tuyệt vời, từ đó cho phép chúng tôi phân phối một số định dạng có hiệu suất cao nhất cho các nhà phát hành trò chơi. Cuối cùng, cách này sẽ giúp tách biệt quy trình đặt quảng cáo trong trò chơi với các quyết định về hoạt động kiếm tiền về loại và số lượng quảng cáo sẽ hiển thị.

Chúng tôi muốn bạn có thể thay đổi chế độ cài đặt kiếm tiền và kiểm soát trải nghiệm người dùng mà không cần phải chỉnh sửa và phát hành phiên bản mới của trò chơi, ban đầu bằng cách chỉ định gợi ý trong thẻ. Nhưng trong các bản phát hành trong tương lai, chúng tôi sẽ có thể cung cấp tính năng kiểm soát trực tiếp trong giao diện người dùng AdSense và AdMob.

Quảng cáo trung gian

Quảng cáo xen kẽ là quảng cáo toàn màn hình, có thể hiển thị tại các thời điểm khác nhau trong trò chơi của bạn, chẳng hạn như khi người chơi bắt đầu trò chơi hoặc sau khi người chơi hoàn thành một cấp độ. Quảng cáo này tạm dừng trò chơi, bao phủ toàn bộ tài liệu và người chơi có thể chọn nhấp vào quảng cáo (trong trường hợp đó, quảng cáo xuất hiện trong một thẻ khác trên trình duyệt) hoặc đóng quảng cáo để cho phép họ tiếp tục trò chơi.

Để đặt quảng cáo xen kẽ, hãy điền vào các trường sau trong cấu hình vị trí:

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

Đối số type là bắt buộc và bạn nên luôn đặt tên cho vị trí của mình. Các lệnh gọi lại khác là không bắt buộc.

Trình tự cuộc gọi

Xem xét trình tự cuộc gọi cho một quảng cáo xen kẽ.

Sơ đồ trình tự lệnh gọi quảng cáo xen kẽ

Mô tả

Quảng cáo xen kẽ – Trình tự cuộc gọi chi tiết
Trò chơi H5 của bạn API Vị trí đặt quảng cáo
  Khởi chạy và tải trước quảng cáo
Chạy trò chơi  

Cơ hội tốt để hiển thị quảng cáo...

adBreak() →

 
 

Có một quảng cáo đang hiển thị và giờ là thời điểm thích hợp để hiển thị quảng cáo...

← beforeAd()
Trò chơi tạm dừng, tắt âm thanh và sẵn sàng hiển thị quảng cáo.

return đối với API →

 
  API Vị trí đặt quảng cáo hiển thị quảng cáo xen kẽ. Người chơi có thể nhấp vào quảng cáo (xuất hiện trong một thẻ mới). Họ phải loại bỏ quảng cáo để tiếp tục chơi trò chơi.
  ← afterAd() được gọi nếu một quảng cáo đã hiển thị
Trò chơi sẽ huỷ tạm dừng và bật tiếng.  
  ← adBreakDone()adBreakDone() luôn được gọi (ngay cả khi quảng cáo không được hiển thị)
Trò chơi ghi nhật ký phân tích về vị trí này.  

Ghi chú

  • adBreak() là một hàm không đồng bộ trả về ngay lập tức.
  • Nếu không có quảng cáo nào để hiển thị cho một vị trí, thì sẽ không có lệnh gọi lại nào được gọi – tức là không có beforeAd(),afterAd() nào được gọi.
  • Để đảm bảo trò chơi không tiếp tục thực thi trong khi quảng cáo đang hiển thị, hãy sử dụng lệnh gọi lại beforeAd() để tắt âm thanh và tạm dừng trò chơi.
  • beforeAd() có tính đồng bộ, API Vị trí đặt quảng cáo sẽ không hiển thị quảng cáo cho đến khi quảng cáo trả về.
  • Khởi động lại trò chơi và bật tiếng khi bạn nhận được lệnh gọi afterAd().
  • Nếu được cung cấp, adBreakDone() sẽ luôn được gọi ngay cả khi quảng cáo không hiển thị ở vị trí này.
  • Việc gọi adBreak() trong khi một quảng cáo khác đang hiển thị sẽ không thành công và cảnh báo sẽ được hiển thị trên bảng điều khiển JavaScript.

Trước video

Quảng cáo trước video là một quảng cáo xen kẽ hiển thị trước khi trò chơi tải giao diện người dùng. Đó là điều đầu tiên người chơi nhìn thấy khi họ di chuyển đến trò chơi của bạn. Do quảng cáo trước video xảy ra rất sớm trong khi tải trang và trò chơi của bạn chưa hiển thị, nên bạn không cần phải thực hiện các lệnh gọi tạm dừng thông thường để tạm dừng và tắt tiếng trò chơi. Thay vào đó, bạn sử dụng lệnh gọi lại adBreakDone() để sắp xếp trình tự bắt đầu trò chơi bằng quảng cáo, tức là hiển thị giao diện người dùng và bắt đầu phát âm thanh. Bạn chỉ có thể kích hoạt một quảng cáo trước video cho mỗi lần tải trang.

Trình tự cuộc gọi

Lệnh gọi cho quảng cáo trước video được thực hiện rất sớm trong khi tải trang. Vì trò chơi của bạn chưa kết xuất giao diện người dùng tại thời điểm này, nên bạn không nên truyền các lệnh gọi lại beforeAd() và afterAd(). Thay vào đó, hãy sử dụng lệnh gọi lại adBreakDone() để bắt đầu trò chơi sau vị trí, vì lệnh này được đảm bảo sẽ được gọi ngay cả khi không có quảng cáo.

Sơ đồ trình tự lệnh gọi của quảng cáo trước video

Khi bạn gọi mã sau, logic ban đầu của trò chơi sẽ đặt quảng cáo trước video. Giao diện người dùng của bạn không được hiển thị trước khi mã này được gọi.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
Trước video – Trình tự chi tiết cuộc gọi
Trò chơi H5 của bạn API Vị trí đặt quảng cáo
  Bắt đầu chạy API và lưu vào bộ nhớ đệm trước khi khởi động quảng cáo
Đang chạy nhưng chưa bắt đầu và chưa hiển thị giao diện người dùng  

adBreak(type:'preroll',…) →

 
 

API Vị trí đặt quảng cáo hoàn tất việc khởi chạy và tải quảng cáo. Nếu có quảng cáo, quảng cáo sẽ hiển thị. Người chơi có thể nhấp vào quảng cáo (xuất hiện trong một thẻ mới). Họ phải đóng lớp này để trò chơi bắt đầu.

 

← adBreakDone() luôn được gọi (ngay cả khi quảng cáo không hiển thị)

Giao diện người dùng của trò chơi sẽ hiển thị trên màn hình và người chơi hiện có thể tương tác. Trò chơi có thể sử dụng đối tượng placementInfo được chuyển đến adBreakDone() khi cần (ví dụ: để ghi lại số liệu phân tích bổ sung).

  

Ghi chú

  • Quảng cáo trước video sẽ luôn cố gắng tải trước quảng cáo:
    • Bạn không cần gọi adConfig(preloadAds: ‘on') với quảng cáo trước video.
  • Giống như các vị trí đặt quảng cáo khác, quảng cáo trước video có thể có hoặc không hiển thị quảng cáo.
  • Không được chuyển beforeAd() và afterAd() vào quảng cáo trước video.
    • Vì quảng cáo trước video chạy trước khi trò chơi bắt đầu, nên bạn không cần tạm dừng hoặc tắt âm thanh trò chơi.
    • Nếu bạn truyền beforeAd() hoặc afterAd() với quảng cáo trước video, lệnh gọi sẽ không thành công và lỗi sẽ được ghi vào bảng điều khiển JavaScript.
  • Quảng cáo trước video tự động đợi API Vị trí đặt quảng cáo khởi chạy và tải trước quảng cáo:
    • Tuy nhiên, có một thời gian chờ (2) ngăn lệnh gọi trì hoãn vô thời hạn. Điều này đảm bảo rằng adBreakDone() được gọi một cách kịp thời và trò chơi của bạn bắt đầu.
    • adBreakDone() luôn được gọi ngay cả khi không có quảng cáo.
  • Bạn nên sử dụng quảng cáo trước video để đặt quảng cáo trước khi trò chơi bắt đầu.
    • Ngoài ra, bạn có thể sử dụng lệnh gọi lại onReady() đến adConfig() làm cơ chế để sắp xếp trình tự logic trò chơi bằng cách khởi chạy API và tải trước quảng cáo.

Quảng cáo có tặng thưởng

Quảng cáo có tặng thưởng cho phép bạn tặng người chơi vật phẩm trong ứng dụng nếu họ chọn xem quảng cáo. Trong khi quảng cáo xen kẽ chọn không sử dụng, thì trình phát sẽ hiển thị quảng cáo và có thể chọn đóng quảng cáo đó. Bạn chọn sử dụng quảng cáo có tặng thưởng. Người chơi chọn xem và khi nào họ muốn xem quảng cáo để nhận phần thưởng.

Không giống như quảng cáo xen kẽ mà người chơi có thể đóng quảng cáo bất cứ lúc nào, để nhận phần thưởng, họ phải xem quảng cáo trong một khoảng thời gian tối thiểu (có thể khác nhau, tuỳ thuộc vào mẫu quảng cáo đang hiển thị).

Vì người chơi không bắt buộc phải sử dụng quảng cáo có tặng thưởng, nên loại quảng cáo này cần tích hợp sâu hơn vào luồng trò chơi của bạn. Bạn phải cung cấp các hàm để hiển thị lời nhắc về phần thưởng trong trò chơi và phân bổ phần thưởng cho người chơi nếu họ xem quảng cáo.

Phần thưởng không được có giá trị bên ngoài ứng dụng, chúng không được có (hoặc dễ dàng được đổi thành) giá trị tiền tệ và không được bán hoặc trao đổi được hàng hoá và dịch vụ, đồng thời bạn không được khuyến khích người chơi nhấp vào quảng cáo. Vui lòng tham khảo chính sách nháp cho quảng cáo xen kẽ và quảng cáo có tặng thưởng để biết thêm thông tin.

Vì người chơi không bắt buộc phải thêm phần thưởng, nên bạn có thể thêm phần thưởng vào bất cứ vị trí nào hợp lý trong trò chơi và có thể sử dụng kèm theo quảng cáo xen kẽ. Giống như quảng cáo xen kẽ, những vị trí này là cơ hội để hiển thị quảng cáo có tặng thưởng. API Vị trí đặt quảng cáo sẽ chỉ gọi mã của bạn nếu một quảng cáo có tặng thưởng thực sự được cung cấp tại một thời điểm cụ thể trong trò chơi của bạn.

Một lần nữa, mục tiêu ở đây là cho phép bạn tích hợp trò chơi của mình với API Vị trí đặt quảng cáo theo thời gian và sau đó sử dụng các tùy chọn kiểm soát trong thẻ hoặc trong AdSense, bạn có thể thay đổi cách kết hợp chính xác các quảng cáo được kích hoạt – mà không phải mã hóa lại và phát hành lại trò chơi.

Loại vị trí có tặng thưởng luôn là 'reward' và có thể sử dụng tất cả các trường trong cấu hình vị trí.

adBreak({
   type: 'reward',                      // 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 it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

Các hàm mới chính là beforeReward(), là trình kích hoạt báo hiệu bạn sẽ hiển thị lời nhắc phần thưởng và adViewed() được gọi khi người chơi đã xem quảng cáo thành công, để bạn có thể phân bổ phần thưởng.

Bạn có thể xác định một vị trí có tặng thưởng như sau:

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

Quảng cáo có tặng thưởng bắt đầu bằng một lời nhắc trong trò chơi của bạn, tặng thưởng cho người chơi nếu họ xem quảng cáo.

Ví dụ về lời nhắc về quảng cáo: Xem video để có thêm mạng

Trình tự cuộc gọi cho quảng cáo có tặng thưởng

Sơ đồ trình tự cuộc gọi có tặng thưởng

Mô tả

Quảng cáo có tặng thưởng – Trình tự cuộc gọi chi tiết
Trò chơi H5 của bạn API Vị trí đặt quảng cáo
  Khởi chạy và lưu trước vào bộ nhớ đệm quảng cáo
Chạy trò chơi  

adBreak(type:'reward', ... ) →

 
 

Có sẵn một quảng cáo, vì vậy, hãy bắt đầu một vị trí đặt quảng cáo có tặng thưởng. beforeReward() được gọi đồng bộ – ngay sau cuộc gọi đến adBreak()

← beforeReward(showAdFn)

Trò chơi hiển thị lời nhắc về phần thưởng. Nhờ đó, người chơi có cơ hội nhận phần thưởng bằng cách xem quảng cáo. Có thể cung cấp nhiều loại phần thưởng (ví dụ: mạng mới hoặc tiền xu).

Người chơi có thể nhấp vào lời nhắc về phần thưởng, loại bỏ chúng hoặc đơn giản là bỏ qua chúng.

Nếu người dùng nhấp vào lời nhắc, trò chơi sẽ lưu trữ loại phần thưởng mà họ đã yêu cầu và gọi showAdFn()...

Tuy nhiên, nếu lời nhắc về phần thưởng bị loại bỏ hoặc bị bỏ qua, thì sẽ không có điều gì xảy ra cho đến khi bạn thực hiện một lệnh gọi khác đến adBreak() với loại vị trí đặt phần thưởng. Tại thời điểm đó, API Vị trí đặt quảng cáo sẽ đặt lại và dọn dẹp trạng thái khỏi lệnh gọi này. Nếu ứng dụng gọi showAdFn từ một điểm chèn quảng cáo trước đó, thì việc này không có hiệu lực.

  

showAdFn() →

 
  ← beforeAd()

Trò chơi tạm dừng, tắt tiếng và sẵn sàng hiển thị quảng cáo

return đối với API →

 
  API sẽ hiển thị quảng cáo. Nó có nút đóng và đếm ngược thời gian còn lại trong quảng cáo.
NẾU người chơi đóng quảng cáo...
  ← adDismissed()
Người chơi đã loại bỏ quảng cáo và trò chơi không trao phần thưởng.  
NẾU KHÔNG THÌ người chơi xem quảng cáo đến hết...
  ← adViewed()
Người chơi đã xem hết quảng cáo và trò chơi phát hành phần thưởng. (Điều này thường xảy ra khi bạn thiết lập một số trạng thái trò chơi rồi sẽ được lấy khi trò chơi khởi động lại với lệnh gọi đến afterAd() bên dưới).  
Sau khi người dùng xem hoặc loại bỏ quảng cáo...
  ← afterAd() được gọi nếu một quảng cáo đã hiển thị
Trò chơi sẽ huỷ tạm dừng và bật tiếng.  
  ← adBreakDone()adBreakDone() luôn được gọi (ngay cả khi quảng cáo không được hiển thị)
Trò chơi ghi nhật ký phân tích về vị trí này.  

Ghi chú

  • adBreak() là một hàm không đồng bộ trả về ngay lập tức.
  • Nếu không có quảng cáo nào để hiển thị cho một vị trí, thì sẽ không có lệnh gọi lại nào được gọi – tức là không có beforeAd() nào, beforeReward() được gọi.
  • Để đảm bảo trò chơi không tiếp tục thực thi trong khi quảng cáo đang hiển thị, hãy sử dụng lệnh gọi lại beforeAd() để tắt âm thanh và tạm dừng trò chơi.
  • beforeAd() có tính đồng bộ, API Vị trí đặt quảng cáo sẽ không hiển thị quảng cáo cho đến khi quảng cáo trả về.
  • Khởi động lại trò chơi và bật tiếng khi bạn nhận được lệnh gọi afterAd().
  • Nếu được cung cấp, adBreakDone() sẽ luôn được gọi ngay cả khi quảng cáo không hiển thị ở vị trí này.
  • Việc gọi adBreak() trong khi một quảng cáo khác đang hiển thị sẽ không thành công và cảnh báo sẽ được hiển thị trên bảng điều khiển JavaScript.