> For the complete documentation index, see [llms.txt](/llms.txt) # 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 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: | Type | Action | Description | | --- | --- | --- | | Consume | `Gs2AdReward:ConsumePointByUserId` | Consume viewing points | | Acquire | `Gs2AdReward:AcquirePointByUserId` | Add viewing points | ```mermaid 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. | Platform | Callback Identifier | | --- | --- | | AdMob (Google Mobile Ads) | `admob` | | Unity Ads | `unityad` | | AppLovin MAX | `applovinmax` | ### 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 ```shell 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 ```shell 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. | Field | Description | | --- | --- | | `allowAdUnitId` | Allowed ad unit ID. The `adUnitId` included in the callback is verified against this value, blocking unauthorized requests. | | `eventKey` | The event key issued in the AppLovin MAX management console. Used to verify that the WebHook was sent from an authorized source. | Example callback URL: ```shell 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 **Unity** ```csharp await AdMobUtil.InitializeAsync( new RequestConfiguration() { TestDeviceIds = new List { "4cd8a25ecc6250e3c140e365e5a543ff", // Test Device ID }, } ); await AdMobUtil.ViewAsync( "ca-app-pub-8090851552121537/9708453802", // Ad Unit ID GameSession // Login Session ); ``` #### Unity Ads **Unity** ```csharp await UnityAdUtil.InitializeAsync( "5416096" // Unity Ads Game ID ); await UnityAdUtil.ViewAsync( "test", // Placement ID GameSession // Login Session ); ``` #### AppLovin MAX **Unity** ```csharp await AppLovinMaxUtil.ViewAsync( "your-sdk-key", // AppLovin SDK Key "your-ad-unit-id", // Ad Unit ID GameSession // Login Session ); ``` ### Get current ad points **Unity** ```csharp var domain = gs2.AdReward.Namespace( namespaceName: "namespace-0001" ).Me( gameSession: GameSession ).Point( ); var item = await domain.ModelAsync(); ``` **Unreal Engine** ```cpp 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. **Unity** ```csharp gs2.AdReward.OnChangePointNotification += notification => { var namespaceName = notification.NamespaceName; var userId = notification.UserId; }; ``` **Unreal Engine** ```cpp 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 [GS2-AdReward API Reference](../../api_reference/ad_reward)