GS2-AdReward

It has become common practice to have players view ads and earn rewards from ad platforms as a monetization method for mobile games. When an ad is viewed correctly, the ad platform notifies GS2 via server-to-server coordination, and rewards are granted by GS2, thereby preventing cheating.

In designs where rewards are granted solely via client-side callbacks, there is a risk of cheating using a tampered SDK. GS2-AdReward provides a mechanism that issues rewards based on trusted viewing-completion events delivered via direct Server-to-Server (S2S) notifications from the ad platform to GS2.

Ad Viewing Point

In general, GS2 exchanges resources by setting compensation and rewards, but since the specifications for server-to-server communication differ among advertising platforms and the granularity of data also differs, GS2-AdReward adds one “Ad Viewing Point” when an ad is confirmed as viewed.

The “Ad Viewing Point” earned can be consumed as a consume action that can be used in GS2-Exchange, GS2-Showcase, and other services. This loosely couples ad viewing with any in-game reward, so the reward design can be reused when adding new ad campaigns.

Transaction Actions

GS2-AdReward provides the following transaction actions:

graph TD
  InGame["Game"] -- view Ad --> ViewAd["Ad"]
  ViewAd -- Ad has been viewed --> AdPlatform2["Ad Platform"]
  ViewAd -- Ad has been viewed --> InGame2["Game"]
  AdPlatform2 -- Notification that ad has been viewed --> AdReward["GS2-AdReward"]
  AdReward --> AddPoint["Give Points"]
  AdReward -- Notify that points have been awarded --> InGame2
  InGame2 -- Exchange viewing points for items --> Exchange["GS2-Exchange"]

Supported Advertising Platforms

GS2-AdReward currently supports the following advertising platforms. Please contact support if you would like additional platforms to be supported.

AdMob Settings

You need to enable “Server Side Verification” in the Ad Unit settings and set the URL issued by GS2. Please refer to the following for the setup procedure.

https://support.google.com/admob/answer/9603226

Configure the namespace settings with the ad unit IDs to be rewarded (allowAdUnitIds). Callbacks from ad units not registered here are ignored, preventing unauthorized issuance of viewing points from unexpected ad units.

Example of Callback URL

https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/admob

Unity Ads Settings

Specify the Game ID issued by Unity Ads and the URL issued by GS2 to have the private key issued. See below for the setup procedure.

https://docs.unity.com/ads/en-us/manual/ImplementingS2SRedeemCallbacks

Set the private key (keys) in the namespace configuration. Multiple keys can be registered when supporting multiple games.

Example of callback URL

https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/unityad

AppLovin MAX Configuration

By adding AppLovin MAX configuration (appLovinMaxes) to the Namespace, points can be awarded from the view completion WebHook.

Example callback URL:

https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/applovinmax

Push Notifications

The main push notifications that can be configured and their setting names are as follows:

• changePointNotification: Notification when points change due to ad viewing

Because the result is not delivered directly to the client until the viewing completion notification arrives from the ad platform via server-to-server coordination (S2S), it is important to inform the client that “points have been granted” through push notifications.

Implementation Example

Start watching videos

You can directly use the SDK of each advertising platform to watch videos. The implementation example here shows an example using the utility classes provided by GS2-SDK. With the utility class, you can automatically wait from viewing completion until the arrival of changePointNotification, allowing simple “waiting for point award” handling on the UI side.

AdMob

    await AdMobUtil.InitializeAsync(
        new RequestConfiguration() {
            TestDeviceIds = new List<string> {
                "4cd8a25ecc6250e3c140e365e5a543ff", // Test Device ID
            },
        }
    );
    await AdMobUtil.ViewAsync(
        "ca-app-pub-8090851552121537/9708453802", // Ad Unit ID
        GameSession // Login Session
    );

Unity Ads

    await UnityAdUtil.InitializeAsync(
        "5416096" // Unity Ads Game ID
    );
    await UnityAdUtil.ViewAsync(
        "test", // Placement ID
        GameSession // Login Session
    );

AppLovin MAX

    await AppLovinMaxUtil.ViewAsync(
        "your-sdk-key", // AppLovin SDK Key
        "your-ad-unit-id", // Ad Unit ID
        GameSession // Login Session
    );

Get current ad points

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

Viewing point accrual callback

When viewing points are increased by an S2S notification from the ad platform, a notification is delivered to the client via changePointNotification. By subscribing to this callback, you can implement UI updates or effects immediately after viewing completion.

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

Other Features

Resetting points

User-held viewing points can be reset (deleted) via the management console or API. This is useful for switching campaigns or for operational adjustments.

Viewing History

Viewing completion notifications received from ad platforms are retained as History. This ensures idempotency by preventing points from being granted twice when a notification with the same transactionId is resent.

Custom Script Triggers

Event triggers can be configured to invoke GS2-Script before and after point processing. These can be utilized for game-specific validation or auditing. Triggers support both synchronous and asynchronous execution, with asynchronous processing enabling external integration through GS2-Script or Amazon EventBridge.

Main event triggers and script setting names are:

• acquirePointScript (completion notification: acquirePointDone): before and after adding points from ad viewing
• consumePointScript (completion notification: consumePointDone): before and after consuming viewing points for item exchanges, etc.

Asynchronous triggers can route through Amazon EventBridge to forward data to external systems for view-count aggregation, BI tool integration, and the like.

Detailed Reference