GS2-AdReward
모바일 게임의 수익화 방법으로 플레이어에게 광고를 시청하게 하고 광고 플랫폼으로부터 보상을 받는 방식도 일반화되었습니다. 광고가 정상적으로 시청되었을 때 광고 플랫폼으로부터 서버 간 연동으로 통지를 받아 GS2에 보상을 지급함으로써 부정행위를 방지할 수 있습니다.
클라이언트 측 콜백만으로 보상을 지급하는 설계에서는 변조된 SDK를 사용한 부정행위가 발생할 위험이 있습니다. GS2-AdReward는 광고 플랫폼에서 GS2로의 직접적인 Server-to-Server(S2S) 통지를 통해 신뢰할 수 있는 시청 완료 이벤트를 계기로 보상을 발행하는 구조를 제공합니다.
시청 포인트
일반적으로 GS2에서는 대가와 보상을 설정하여 리소스 교환을 수행하지만, 서버 간 통신의 사양이 광고 플랫폼마다 다르고 데이터의 세분화 정도도 다르기 때문에 GS2-AdReward에서는 광고 시청이 확인되었을 때 《시청 포인트》를 1포인트 가산하도록 되어 있습니다.
획득한 《시청 포인트》는 GS2-Exchange나 GS2-Showcase 등에서 사용 가능한 소비 액션으로 소비할 수 있습니다. 이를 통해 게임 내 모든 보상과 광고 시청을 느슨하게 결합할 수 있으므로, 새로운 광고 캠페인을 추가할 때도 보상 설계를 재사용할 수 있습니다.
트랜잭션 액션
GS2-AdReward에서는 다음과 같은 트랜잭션 액션을 제공하고 있습니다.
| 종별 | 액션 | 설명 |
|---|---|---|
| 소비 | Gs2AdReward:ConsumePointByUserId | 시청 포인트 소비 |
| 입수 | Gs2AdReward:AcquirePointByUserId | 시청 포인트 가산 |
graph TD InGame["게임"] -- 광고를 시청 --> ViewAd["광고"] ViewAd -- 광고 시청 완료 --> AdPlatform2["광고 플랫폼"] ViewAd -- 광고 시청 완료 --> InGame2["게임"] AdPlatform2 -- 광고 시청 완료를 통지 --> AdReward["GS2-AdReward"] AdReward --> AddPoint["포인트를 지급"] AdReward -- 포인트 지급을 통지 --> InGame2 InGame2 -- 시청 포인트와 아이템을 교환 --> Exchange["GS2-Exchange"]
지원하는 광고 플랫폼
현재 GS2-AdReward는 다음 광고 플랫폼을 지원하고 있습니다. 추가 지원을 희망하시는 경우 지원팀으로 문의해 주십시오.
| 플랫폼 | 콜백 식별자 |
|---|---|
| AdMob(Google Mobile Ads) | admob |
| Unity Ads | unityad |
| AppLovin MAX | applovinmax |
AdMob 설정
《광고 단위》 설정에서 《서버 측 검증》을 활성화하고, GS2가 발급한 URL을 설정해야 합니다. 설정 절차는 다음을 확인해 주십시오.
https://support.google.com/admob/answer/9603226
네임스페이스 설정에 보상 지급 대상으로 삼을 광고 단위ID(allowAdUnitIds)를 설정해 주십시오.
여기에 등록되지 않은 광고 단위로부터의 콜백은 무시되므로, 예상하지 못한 광고 단위에 의한 부정한 시청 포인트 발행을 방지할 수 있습니다.
콜백 URL 예시
https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/admobUnity Ads 설정
Unity Ads 측에서 Game ID와 GS2가 발급한 URL을 설정하고, 서명 검증용 비밀 키를 발급받으십시오. 설정 절차는 다음을 확인해 주십시오.
https://docs.unity.com/ads/en-us/manual/ImplementingS2SRedeemCallbacks
네임스페이스 설정에 비밀 키(keys)를 설정해 주십시오. 여러 게임에 대응하는 경우 여러 개의 키를 등록할 수 있습니다.
콜백 URL 예시
https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/unityadAppLovin MAX 설정
Namespace에 AppLovin MAX용 설정(appLovinMaxes)을 추가하면, 시청 완료 웹훅으로부터 포인트를 지급할 수 있게 됩니다.
| 필드 | 설명 |
|---|---|
allowAdUnitId | 허용할 광고 단위 ID. 콜백에 포함된 adUnitId를 대조하여 부정한 요청을 차단합니다. |
eventKey | AppLovin MAX 관리 화면에서 발급한 이벤트 키. 웹훅이 정규 발신자로부터 전송되었음을 검증합니다. |
콜백 URL 예시:
https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/applovinmax푸시 알림
설정할 수 있는 주요 푸시 알림과 설정명은 다음과 같습니다.
changePointNotification: 광고 시청으로 포인트가 변동되었을 때 통지
서버 간 연동(S2S)으로 광고 플랫폼으로부터 시청 완료 통지가 도착할 때까지는 클라이언트 측에 직접 결과가 전달되지 않으므로, 푸시 알림을 통해 클라이언트에 “포인트가 지급되었다"는 사실을 전달하는 것이 중요합니다.
구현 예제
동영상 시청 시작
각 광고 플랫폼의 SDK를 직접 이용하여 동영상을 시청해도 문제없습니다.
여기서의 구현 예제는 GS2-SDK에서 제공하는 유틸리티 클래스를 사용한 구현 예제를 보여줍니다.
유틸리티 클래스를 이용하면 시청 완료부터 changePointNotification 도착까지 자동으로 대기할 수 있으므로, UI 측에서 “포인트 지급 대기” 처리를 단순하게 구현할 수 있습니다.
AdMob
await AdMobUtil.InitializeAsync(
new RequestConfiguration() {
TestDeviceIds = new List<string> {
"4cd8a25ecc6250e3c140e365e5a543ff", // 테스트 디바이스 ID
},
}
);
await AdMobUtil.ViewAsync(
"ca-app-pub-8090851552121537/9708453802", // 광고 단위 ID
GameSession // 로그인 세션
);# AdMob에서 제공하는 Godot 플러그인으로 리워드 광고를 초기화·표시합니다.
# 서버 측 검증용 커스텀 데이터에 GS2 사용자 ID를 설정합니다.
var custom_data = game_session.get_user_id()Unity Ads
await UnityAdUtil.InitializeAsync(
"5416096" // Unity Ads 게임 ID
);
await UnityAdUtil.ViewAsync(
"test", // Placement ID
GameSession // 로그인 세션
);# Unity Ads에서 제공하는 Godot 플러그인으로 리워드 광고를 초기화·표시합니다.
# 서버 측 검증용 플레이어 ID에 GS2 사용자 ID를 설정합니다.
var player_id = game_session.get_user_id()AppLovin MAX
await AppLovinMaxUtil.ViewAsync(
"your-sdk-key", // AppLovin SDK 키
"your-ad-unit-id", // 광고 단위 ID
GameSession // 로그인 세션
);# AppLovin MAX에서 제공하는 Godot 플러그인으로 리워드 광고를 표시합니다.
# 서버 측 콜백용 커스텀 데이터에 GS2 사용자 ID를 설정합니다.
var custom_data = game_session.get_user_id()현재 광고 포인트 취득
var domain = gs2.AdReward.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Point(
);
var item = await domain.ModelAsync(); const auto Domain = Gs2->AdReward->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->Point(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.ad_reward.namespace_(
"namespace-0001"
).me(game_session).point(
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result시청 포인트 가산 콜백
광고 플랫폼으로부터의 S2S 통지에 의해 시청 포인트가 증가했을 때, changePointNotification을 통해 클라이언트에 통지가 도착합니다.
이 콜백을 구독함으로써 시청 완료 직후의 UI 업데이트나 연출을 구현할 수 있습니다.
gs2.AdReward.OnChangePointNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
}; Gs2->AdReward->OnChangePointNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto UserId = Notification->UserIdValue;
});ez.gs2.notification_received.connect(func(message):
if message.subject != "Gs2AdReward:ChangePointNotification":
return
var notification = message.parse()
if notification == null:
return
var namespace_name = notification.namespace_name
var user_id = notification.user_id
)기타 기능
포인트 리셋
관리 화면이나 API를 통해 사용자가 보유한 시청 포인트를 리셋(삭제)할 수 있습니다. 캠페인 전환이나 운영상의 조정이 필요한 상황에서 이용할 수 있습니다.
시청 이력
광고 플랫폼으로부터 받은 시청 완료 통지는 History로 보관됩니다.
동일한 transactionId의 통지가 재전송되었을 때 포인트가 이중으로 지급되지 않도록 하는 멱등성 확보에 이용됩니다.
커스텀 스크립트 트리거
포인트 처리 전후에 GS2-Script를 호출하는 이벤트 트리거를 설정할 수 있습니다. 게임 고유의 검증이나 감사를 수행할 때 활용할 수 있습니다. 트리거는 동기·비동기 실행 방식을 선택할 수 있으며, 비동기 처리에서는 GS2-Script나 Amazon EventBridge를 이용한 외부 연동도 가능합니다.
설정할 수 있는 주요 이벤트 트리거와 스크립트 설정명은 다음과 같습니다.
acquirePointScript(완료 통지:acquirePointDone): 광고 시청 등으로 포인트를 가산하기 전후consumePointScript(완료 통지:consumePointDone): 시청 포인트를 아이템 교환 등으로 소비하기 전후
비동기 트리거에서 Amazon EventBridge를 경유하여 시청 횟수 집계나 BI 도구로의 데이터 연동과 같은 외부 시스템으로의 전송이 가능합니다.