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) を追加することで、視聴完了 WebHook からポイントを付与できるようになります。

フィールド 説明
allowAdUnitId 許可する広告ユニット ID。コールバックに含まれる adUnitId を照合し、不正なリクエストを遮断します。
eventKey AppLovin MAX 管理画面で発行したイベントキー。WebHook が正規の発信元から送信されたことを検証します。

コールバック 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 // ログインセッション
    );

Unity Ads

    await UnityAdUtil.InitializeAsync(
        "5416096" // Unity Ads のゲームID
    );
    await UnityAdUtil.ViewAsync(
        "test", // Placement ID
        GameSession // ログインセッション
    );

AppLovin MAX

    await AppLovinMaxUtil.ViewAsync(
        "your-sdk-key", // AppLovin の SDK キー
        "your-ad-unit-id", // 広告ユニットID
        GameSession // ログインセッション
    );

現在の広告ポイントを取得

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

視聴ポイントの加算コールバック

広告プラットフォームからの 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;
    });

その他の機能

ポイントのリセット

管理画面や API を通じて、ユーザーの保持している視聴ポイントをリセット（削除）できます。 キャンペーンの切り替えや、運営上の調整が必要なシーンで利用できます。

視聴履歴

広告プラットフォームから受け取った視聴完了通知は History として保持されます。 同じ transactionId の通知が再送されてきた場合に二重でポイントを付与しないための冪等性確保に利用されます。

カスタムスクリプトトリガー

ポイント処理の前後に GS2-Script を呼び出すイベントトリガーを設定できます。ゲーム固有の検証や監査を行う際に活用できます。トリガーは同期・非同期の実行方式を選択でき、非同期処理では GS2-Script や Amazon EventBridge を利用した外部連携も可能です。

設定できる主なイベントトリガーとスクリプト設定名は以下の通りです。

  • acquirePointScript（完了通知: acquirePointDone）: 広告視聴などでポイントを加算の前後
  • consumePointScript（完了通知: consumePointDone）: 視聴ポイントをアイテム交換などで消費する前後

非同期トリガーから Amazon EventBridge を経由して、視聴回数の集計や BI ツールへのデータ連携といった外部システムへの転送が行えます。

詳細なリファレンス

GS2-AdReward リファレンス