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}/admob

Unity 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}/unityad

AppLovin 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 도구로의 데이터 연동과 같은 외부 시스템으로의 전송이 가능합니다.

상세 레퍼런스

GS2-AdReward API 레퍼런스