Overview
com.111percent.gamebase.marketings.percent-ads
com.111percent.gamebase.marketings.percent-ads-max
무엇인가요?
광고 Mediation을 쉽게 적용할 수 있도록 돕는 패키지예요.
제공하는 Mediation 종류
- AppLovin Max
광고 적용 방법
광고모듈 사용전 안내
Percent Ads 모듈에서는 광고 이벤트 로그를 전송합니다.
이벤트 로그의 전송을 위해서 EventLogging 모듈의 Initialize가 필요합니다.
Initialize 방법은 가이드 문서를 참고해 주세요.
가이드 문서 링크 : Event Logging Service
사용방법
설치방법
Window/Package Manager 열기
Package : My Registry 선택
Percent Ads 설치 (
com.111percent.gamebase.marketings.percent-ads
)
Mediation 활성화 방법
Percent/Advertisement Setting 에디터를 오픈합니다.
필요한 Mediation을 활성화합니다.
🔧 설정
Max Mediation
해당 윈도우에서 Sdk Key, AdMob AppId, Ad Unit ID를 입력해주세요.
Max Mediation 설정은 Open Integration Manager 버튼을 누르거나,
Unity 메뉴에서 Applovin/Integration Manager를 누르세요.
Network를 추가하려면 Mediated Networks 항목에서 Install이 필요합니다.
Applovin Integration Manager에서 Max Mediation에 대한 설정을 지정할 수 있습니다.
‼️Privacy Settings 체크 해제하기‼️
User Agreement v2.0.0~ 패키지를 사용하는 경우, ATT(App Tracking Transparency), Google UMP(User Messaging Platform) 등 Privacy 관련 설정은 이미 끝났습니다. MaxMediation에서 중복으로 설정하지 않기 위해 체크를 해제합니다.
Max Mediation 설정에 대한 자세한 가이드는 공식 문서를 참고하세요.
⚠️ [Deprecated] 자동 초기화 옵션은 v1.2.0부터 제거됐습니다.
- User Agreement 프로세스 이후에 초기화를 호출돼서 자동 초기화 시점을 특정 불가.
초기화
MaxMediation을 사용할 경우 MaxSdk.SetHasUserConsent, MaxSdk.SetIsAgeRestrictedUser, MaxSdk.SetDoNotSell 설정이 필요하다.
MaxSdk.SetHasUserConsent만 클라이언트 개발자가 직접 설정하고 MaxSdk.SetIsAgeRestrictedUser, MaxSdk.SetDoNotSell은 패키지 내부에서 자체적으로 설정한다.
🔖 MaxMediation 관련 사내 결정 사항 (2024.03.08)
MaxSdk.SetHasUserConsent
- iOS 14.5 이상의 유저인 경우 ATT 동의 여부
- GDPR 대상 국가의 경우 UMP 동의 여부
- 위의 권한이 모두 있는 경우에 개인 맞춤형 광고 노출이 가능하다
MaxSdk.SetDoNotSell, MaxSdk.SetIsAgeRestrictedUser
- 일단 대응하지 않고, 추후 문제가 되면 대응한다.
- 패키지 내부에 하드코딩으로 처리했다.
참고 문서
private void InitializeAdManager()
{
// UserAgreement v2.0.0~ 를 사용할 경우
bool hasUserConsent = UserAgreementManager.AttService.IsTrackingAuthorized &&
UserAgreementManager.UmpService.ConsentResult.CanShowPersonalizedAds;
MaxSdk.SetHasUserConsent(hasUserConsent: hasUserConsent);
AdManager.Initialize(adMediation: new MaxMediation());
}
기본적인 API 사용 예시
//Banner
private void Start()
{
AdManager.Instance.LoadBanner();
}
private void ShowBanner()
{
AdManager.Instance.ShowBanner();
}
private void HideBanner()
{
AdManager.Instance.HideBanner();
}
//Interstitial
private void ShowInterstitial()
{
if (AdManager.Instance.CanShowInterstitial())
{
AdManager.Instance.ShowInterstitial(
new AdEventParams("set a placement for ads event logging"));
}
else
{
AdManager.Instance.LoadInterstitial();
}
}
//RewardVideo
private void ShowRewardVideo()
{
if (AdManager.Instance.CanShowRewardVideo())
{
AdManager.Instance.ShowRewardVideo(
new AdEventParams("set a placement for ads event logging"),
rewarded => PercentAdDebug.Log($"received rewarded: {rewarded}",
nameof(AdManager)));
}
else
{
AdManager.Instance.LoadRewardVideo();
}
}
AdEventParams는 광고 이벤트 로그 전송을 위한 구조체 입니다.
public readonly struct AdEventParams
{
public readonly string placement;//광고 로그 공통 params
public readonly string tier;//광고 로그 공통 params
public readonly Dictionary<string, object> extraParams;//광고 로그 커스텀 params
}
이벤트 로그 전송하기
❗️ad_click은 클라이언트 개발자가 직접 전송해야 합니다
ad_click 외에 다른 공통 광고 로그는 패키지 내부에서 자체 전송합니다.
- 🤔 패키지 내부에서 ad_click을 내부에서 자체 전송하지 않는 이유?
- 클릭, 즉 유저의 Interaction 시점을 알 수 없음
- 광고 Show는 반드시 클릭이 아니더라도 보여줄 수 있다. 예를 들면 스테이지 클리어 이후 전면 광고 노출이 가능하다. 따라서, Show를 호출한다고 패키지 내부에서 무조건 클릭이라고 판정 불가.
ad_click 이벤트 전송하기
// 플레이어가 Reward 광고 버튼 클릭할 때 이벤트 전송하기
AdEventLogger.SendAdEventLog(
eventName: AdEventLogger.EventName_Click,
adType: AdEventLogger.AdType_RewardVideo,
adEventParams: AdEventParams.Empty
);
// 플레이어가 Interstitial 광고 버튼 클릭할 때 이벤트 전송하기
AdEventLogger.SendAdEventLog(
eventName: AdEventLogger.EventName_Click,
adType: AdEventLogger.AdType_Interstitial,
adEventParams: AdEventParams.Empty
);
Callback 등록 예시
//로드완료 시 callback
AdCallbacks.Banner.OnLoadedEvent += (isSuccess) => { };
AdCallbacks.Interstitial.OnLoadedEvent += (isSuccess) => { };
AdCallbacks.RewardVideo.OnLoadedEvent += (isSuccess) => { };
//광고종료 시 callback
AdCallbacks.Interstitial.OnDismissedEvent += () => { };
AdCallbacks.RewardVideo.OnDismissedEvent += () => { };
//보상형 광고에서 보상을 받은경우 callback
AdCallbacks.RewardVideo.OnReceivedRewardEvent += () => { };
추가 설정
- Build Settings → PlayerSettings → Android → Custom Main Gradle Template 체크 확인
Custom Main Gradle Template 체크하는 이유?
라이브러리 의존성 리졸브 주체를 EDM4U → Gradle로 옮기기 위함
EDM4U(External Dependency Manager for Unity) 리졸브로 물리 aar 파일을 다운받을 경우 사용 가능한 최신 버전을 다운받으므로 버전 고정할 수 없음 (리졸브 시점에 따라 다른 버전을 받아 옴)
- EDM4U Force Resolve
- Assets/Plugins/mainTemplate.gradle 파일 실행 & 의존성 기입 확인
비활성화
비활성화 시 Assets 폴더 밑에 Mediation Sdk, 관련 설정 파일 삭제에 대한 경고 메시지가 뜨고, 확인을 누르면 비활성화 됩니다.
트러블 슈팅
- 모든 설정이 진행된 이후에 모바일에서 광고가 나오지 않을 경우 광고 소진 이슈 인지 확인해주세요. 광고가 소진되어 제공되는 광고가 없을 경우 아래와 같은 에러로그가 발생합니다.
ErrorInfo code: NoFill, MAX returned no eligible ads from any mediated networks for this app/device
Change Log
1.3.0
✨ 추가됨:
- 패키지 내부 전송 이벤트 로그
- FirebaseAnalytics에 ad_impression 로그 전송
🔑 필수 조건:
- Google Analytics (Firebase Analytics) 패키지 PPM(Percent Package Manager)으로 설치하기
- EventLoggerManager.Initialize할 때, FirebaseAnalyticsEventLogger 구현체 등록하기
- 패키지 내부 전송 이벤트 로그
1.2.2
🐛 이슈 해결:
- ad_show 이벤트 로그 전송할 때, ad_completed 이벤트에 전달한 파라미터가 같이 전달되던 이슈 해결
- 이벤트 등록 로직 개선하여 메모리 누수 해결
1.2.1
🐛 이슈 해결:
- 유니티 에디터에서 플레이 모드 종료시, static 객체가 남아있던 이슈 해결
1.2.0
🔑 필수 조건:
- UserAgreement Package 2.0.0~ 이상을 사용할 경우
- Editor Window > Percent > Advertisement Setting > Open Integration Manager > Applovin Integration Manager 열기 > Privacy Settings 체크 해제하기
⛔ 제거됨:
- 광고 모듈 자동 초기화 기능 제거
- 패키지는 광고 모듈의 자동 초기화 시점을 특정할 수 없음
- 광고 모듈의 초기화는 User Agreement 절차 이후에 직접 호출해야 됨.
🗝️ 지원 종료:
- 개인정보 보호 관련 API 인터페이스 제거
🔧 변경됨:
광고 공통 이벤트 로그 이름 변경
- ad_click 상황은 클라이언트 개발자가 직접 이벤트 전송
- ad_conversion은 패키지 내부에서 이벤트 자체 전송
*ad_click: 플레이어가 광고 시청 버튼을 클릭한 상황
*ad_conversion: 플레이어가 광고 시청 중에 광고 콘텐츠를 클릭하여 다른 페이지로 전환되는 상황
- UserAgreement Package 2.0.0~ 이상을 사용할 경우
1.1.1
✨ 추가됨:
- 패키지 샘플 추가