GS2-AdReward

Ad reward feature

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 GS2, thereby preventing cheating.

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-Reward adds one “ad viewer point” when an advertisement is viewed. GS2-Reward adds one “Ad Viewing Point” when an ad is viewed.

The “Ad Viewing Point” earned can be consumed as a spend action that can be used in GS2-Exchange, GS2-Showcase, and other services.

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 to add additional support.

AdMob(Google Mobile Ads)
Unity Ads

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 setting procedure.

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

Set the ad unit ID to be rewarded in the namespace settings.

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 in the namespace configuration.

Example of callback URL

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

AppLovin MAX Configuration

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

Registering allowed ad unit IDs (allowAdUnitId) enables verification of the adUnitId included in the callback, blocking unauthorized requests. Setting an event key (eventKey) allows verification that the WebHook was sent from an authorized source.

Example callback URL:

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

Implementation Example

Start watching videos

You can directly use the SDK of each advertising platform to watch videos. The implementation example here shows an implementation example using the utility classes provided by GS2-SDK.

AdMob

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

Unity Ads

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

Get current 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

    gs2.AdReward.OnChangePointNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
    };

    Gs2->AdReward->OnChangePointNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
    });

Other Features

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 acquiring points from ad viewing
consumePointScript (completion notification: consumePointDone): before and after consuming viewing points for item exchanges

Detailed Reference

API Reference