adBreak()

함수 서명:

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

adBreak() 매개변수

이름 유형 설명
모든 게재위치 유형
type 문자열

게재위치의 유형입니다. 값:

  • 'preroll' 게임 로드 전(UI 렌더링 전)
  • 'start' 게임플레이가 시작되기 전(UI 렌더링 후)
  • 'pause' 플레이어가 게임을 일시중지함
  • 'next' 플레이어가 다음 레벨로 이동
  • 'browse' 플레이어가 게임플레이 외부의 옵션을 탐색함
  • 'reward' 보상형 광고
name 문자열 (선택사항) 게임 내 특정 광고 게재위치의 이름. 이는 내부 식별자로 플레이어에게 표시되지 않습니다. 향후 출시 버전에서는 추가 보고 및 최적화 기능을 사용 설정하는 데 이 식별자가 사용될 수 있습니다.

모든 게재위치의 이름을 지정하는 것이 좋습니다.
beforeAd 함수 (선택사항) 광고가 표시되기 전에 호출됩니다. 게임을 일시중지하고 음소거해야 합니다. 이 작업은 동시에 수행되어야 합니다. 이 콜백이 완료된 직후 광고가 표시됩니다.
afterAd 함수 (선택사항) 광고가 완료된 후 호출됩니다(이유 무관). 보상형 광고의 경우 플레이어 동작에 따라 adDismissed 또는 adViewed 이후에 호출됩니다. 이 함수는 게임 흐름을 재개하기 위해 사용됩니다. 예를 들어 음소거를 해제하고 다음 레벨을 시작하는 데 사용합니다.
adBreakDone 함수 (선택사항) 광고가 전혀 게재되지 않았더라도 adBreak()의 마지막 단계에서 항상 호출됩니다. 함수는 다음과 같이 정의된 placementInfo 객체를 인수로 사용합니다. 
{
    breakType: '<type>',
    breakName: '<name>',
    breakFormat: 'interstitial|reward',
    breakStatus:  'error|noAdPreloaded|...|viewed',
}
게재위치 정보 객체에 대한 자세한 설명은 adBreakDone 및 placementInfo()를 참고하세요.
보상형 게재위치 전용...
beforeReward 함수 보상형 광고를 사용할 수 있는 경우에 호출됩니다. 함수는 보상형 광고 표시를 위해 호출해야 하는 단일 인수 showAdFn()를 사용해야 합니다.
adDismissed 함수 플레이어가 광고를 닫을 때만 보상형 광고가 호출됩니다. 이는 광고가 끝나기 전 플레이어가 광고를 닫았을 때에만 호출됩니다. 이 경우 보상이 제공되어서는 안 됩니다.
adViewed 함수 플레이어가 광고를 완료했을 때 보상형 광고만 호출하고 보상이 제공되어야 합니다.

adBreakDone() and placementInfo

Ad Placement API에 표시할 광고가 없는 경우 전달 전후의 다양한 콜백을 호출하지 않습니다. 그러나 adBreakDone() 콜백을 제공하면 광고가 표시되지 않더라도 항상 호출됩니다. 이렇게 하면 게재위치에 대한 추가 분석 로깅과 같이 게재위치에 대해 수행해야 하는 추가 작업을 처리할 수 있습니다.

adBreakDone() 함수는 다음과 같이 정의된 placementInfo 객체를 인수로 사용합니다.

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

여기서 이 객체 내의 필드는 다음과 같은 시맨틱스를 갖습니다.

  • breakType은 adBreak()에 전달되는 유형 인수입니다.
  • breakName은 adBreak()에 전달되는 이름 인수입니다.
  • breakStatus는 이 게재위치의 상태이며 다음 값 중 하나입니다.
breakStatus 이유
'notReady' Ad Placement API가 초기화되지 않았습니다.
'timeout' Ad Placement API가 응답하는 데 너무 오래 걸려 게재위치 시간이 초과되었습니다.
'invalid' 게재위치가 유효하지 않아 무시되었습니다. 예를 들어 페이지 로드당 프리롤 게재위치가 하나만 있어야 하며 이 상태에서는 후속 프리롤이 실패합니다.
'error' 콜백에 자바스크립트 오류가 발생했습니다.
'noAdPreloaded' 광고가 미리 로드되지 않아 이 게재위치를 건너뛰었습니다.
'frequencyCapped' 이 게재위치에 최대 게재빈도가 적용되어 광고가 게재되지 않았습니다.
'ignored' 사용자가 다음 게재위치에 도달하기 전에 리워드 프롬프트를 클릭하지 않았습니다. 즉, 다음 adBreak() 전에 showAdFn()이 호출되지 않았습니다.
'other' 다른 이유로 광고가 게재되지 않았습니다. (예: 광고를 아직 가져오는 중이거나 화면의 크기가 조절되거나 화면이 회전되어 이전에 캐시된 광고가 삭제되었습니다.)
'dismissed' 사용자가 보상형 광고를 끝까지 시청하기 전에 닫음
'viewed' 사용자가 광고를 시청함

참고: adBreakDone()은 항상 adBreak()가 호출하는 마지막 콜백입니다.

광고가 표시된 후 afterAd()를 사용하여 게임 일시중지를 해제하면, 게임이 다시 시작된 후 adBreakDone()가 호출됩니다. 로깅 분석과 같은 방식이 적절할 수 있지만, 게임을 다시 시작하기 전에 추가 작업을 처리하려면 afterAd()에서 adBreakDone()으로 로직을 일시중지 해제해야 합니다.