references/android-rewarded.md
# AI Integration Agent Instructions for Rewarded Ads
## Required Imports
Use the following imports to implement a rewarded ad:
```
import com.google.android.libraries.ads.mobile.sdk.common.AdRequest
import com.google.android.libraries.ads.mobile.sdk.common.AdLoadCallback
import com.google.android.libraries.ads.mobile.sdk.common.FullScreenContentError
import com.google.android.libraries.ads.mobile.sdk.common.LoadAdError
import com.google.android.libraries.ads.mobile.sdk.rewarded.OnUserEarnedRewardListener
import com.google.android.libraries.ads.mobile.sdk.rewarded.RewardedAd
import com.google.android.libraries.ads.mobile.sdk.rewarded.RewardedAdEventCallback
```
## Method Signatures
Use the following method signatures to implement rewarded ads:
The `AdRequest` object takes the ad unit ID:
```
AdRequest.Builder(adUnitId: String).build()
```
The method signature to load an ad from `RewardedAd`:
```
fun load(
adRequest: AdRequest,
adLoadCallback: AdLoadCallback<RewardedAd>
): Unit
```
The `AdLoadCallback` interface is defined as:
```
interface AdLoadCallback<T> {
fun onAdLoaded(ad: T): Unit
fun onAdFailedToLoad(adError: LoadAdError): Unit
}
```
## Gotchas
**UI Threading**: **MANDATORY**: Callbacks in GMA-Next Gen SDK are invoked on a
background thread. **ALL UI-RELATED OPERATIONS** (e.g., Toasts, View updates,
Fragment transactions) **MUST** be wrapped in `runOnUiThread {}` or
`Dispatchers.Main.launch {}` within GMA SDK callbacks. SKIPPING THIS STEP WILL
CAUSE THE APPLICATION TO CRASH.
## Rewarded ad workflow
1. **Load the ad**
2. **Register for ad event callbacks**
- [ ] Set the `adEventCallback` on the `RewardedAd` object.
* Drop the reference to the rewarded ad when the ad is dismissed or
fails to show.
3. **Add a UI element to view the ad for a reward**
* Rewarded ads **must never be shown automatically**. Users must
explicitly opt in.
* Add a UI element, such as a button, that shows the ad upon user
interaction.
4. **Show the ad**
* The `show()` method requires an `OnUserEarnedRewardListener`.
5. **Verify the implementation**: Verify the build to ensure there are no
compile errors:
- [ ] Run `gradle build -x test` to confirm a successful clean build.
Resolve any GMA SDK related compile errors.
### Links
Additional documentation:
- https://developers.google.com/admob/android/next-gen/rewarded.md.txt
references/ios-rewarded.md
# AI Integration Agent Instructions for Rewarded Ads
## Gotchas
Google Mobile Ads SDK uses `NS_SWIFT_NAME` macros to provide idiomatic Swift
names.
## Rewarded ad workflow
1. **Load the ad**
* For Swift code, use `async/await` instead of a completion handler.
2. **Register for ad event callbacks**
- [ ] Set the `fullScreenContentDelegate` on the `RewardedAd` object.
* Drop the reference to the rewarded ad when the ad is dismissed or
fails to show.
3. **Add a UI element to view the ad for a reward**
* Rewarded ads **must never be shown automatically**. Users must
explicitly opt in.
* Add a UI element, such as a button, that shows the ad upon user
interaction.
4. **Show the ad**
* **ViewController Parameter:** The `rootViewController` parameter in the
`present(from:)` method is an optional parameter and can be set to `nil`.
* The `present(from:)` method requires a `UserDidEarnRewardHandler`
object.
5. **Verify the implementation**: Verify the build to ensure there are no
compile errors:
- **If `xcodebuild` is available**: Run `xcodebuild` to programmatically
verify that the iOS project compiles properly with the GMA SDK. Resolve
any GMA-SDK related compile errors.
- **If `xcodebuild` is NOT available**: Output instructions directing the
user to build the project in Xcode and manually verify there are no
compile errors.
### Links
Additional documentation:
- https://developers.google.com/admob/ios/rewarded.md.txt
references/unity-rewarded.md
# AI Integration Agent Instructions for Unity Rewarded Ads
## Required Imports
Use the following imports to implement a rewarded ad:
```c#
using System;
using UnityEngine;
using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
```
## Rewarded Ad Workflow
1. **Load the ad**:
Use the static `RewardedAd.Load()` method passing the ad unit ID,
an `AdRequest` object, and a completion callback
(`Action<RewardedAd, LoadAdError>`):
```c#
// Test ad unit IDs. Replace with your own ad unit IDs.
#if UNITY_ANDROID
string adUnitId = "ca-app-pub-3940256099942544/5224354917";
#elif UNITY_IPHONE
string adUnitId = "ca-app-pub-3940256099942544/1712485313";
#else
string adUnitId = "unused";
#endif
```
```c#
RewardedAd.Load(adUnitId, new AdRequest(),
(RewardedAd ad, LoadAdError error) =>
{
if (error != null || ad == null)
{
// Handle the error.
return;
}
rewardedAd = ad;
});
```
Always destroy any existing `RewardedAd` object before loading a new ad.
2. **Register for ad event callbacks**:
Subscribing to ad events on the `RewardedAd` object is optional and depends
on your application requirements:
- `OnAdPaid`: Subscribe to log estimated ad revenue (`AdValue`) for
impression-level ad monetization tracking.
- `OnAdImpressionRecorded`: Subscribe to track ad impressions in
internal telemetry or third-party analytics platforms.
- `OnAdClicked`: Subscribe to record user clicks on the ad.
- `OnAdFullScreenContentOpened`: Subscribe to pause game audio,
timers, or gameplay loops when the rewarded ad covers the screen.
- `OnAdFullScreenContentClosed`: Subscribe to resume game audio or
gameplay loops when the ad is dismissed. Destroy the `RewardedAd` object
(`rewardedAd.Destroy()`) and reload another ad (`RewardedAd.Load()`) so a fresh
ad is ready for the next transition point.
- `OnAdFullScreenContentFailed`: Subscribe to log display errors if the
rewarded ad fails to show.
Ensure background ad callbacks interacting with Unity objects
(`UnityEngine`) are explicitly scheduled on the main thread using
`MobileAdsEventExecutor.ExecuteInUpdate()`, because Unity APIs are not
thread-safe and must be called from the main thread.
```c#
rewardedAd.OnAdFullScreenContentOpened += () =>
{
MobileAdsEventExecutor.ExecuteInUpdate(() =>
{
// Interact with UnityEngine objects on the main thread here.
});
};
```
3. **Add a UI element to view the ad for a reward**:
**MANDATORY**: You MUST explicitly mention or demonstrate adding an
interactive UI element (such as a Button) to trigger `ShowRewardedAd()`.
Rewarded ads must never show automatically.
4. **Show the ad**:
Check `CanShowAd()` on the `RewardedAd` object along with passing an
`Action<Reward>` callback to the `Show()` method. Include a null check to
avoid exceptions. Hook this method to an interactive UI Button:
```c#
// Call this method from a UI Button click event:
public void ShowRewardedAd()
{
if (rewardedAd != null && rewardedAd.CanShowAd())
{
rewardedAd.Show((Reward reward) =>
{
// Reward the user.
Debug.Log($"Rewarded! Amount: {reward.Amount}, Type: {reward.Type}");
});
}
}
```
5. **Verify the implementation**: Ensure there are no compilation errors:
- [ ] Verify the Unity Console has no C# script compile errors or
missing GoogleMobileAds namespace references.
### Links
Additional documentation:
- https://developers.google.com/admob/unity/rewarded.md.txt
SKILL.md
---
name: google-mobile-ads-rewarded
description: >-
Provides instructions for implementing, integrating, or configuring Google
Mobile Ads (GMA) SDK rewarded ads in Android, iOS, or Unity mobile
applications. Use when the task involves setting up rewarded ads. Don't use
for "rewarded interstitial" ads.
metadata:
version: "1.1.0"
category: GoogleAds
---
# Google Mobile Ads SDK - Rewarded Ads
Rewarded ads reward users with in-app items for interacting with full-screen
ads. Rewarded ads are served after a user explicitly opts in to view a rewarded
ad.
## Workflow
1. **Determine the user's platform**: Identify if the project is Android,
iOS, or Unity. If unclear, ask before proceeding.
2. **Read the platform guide** for implementation details:
- Android: `references/android-rewarded.md`
- iOS: `references/ios-rewarded.md`
- Unity: `references/unity-rewarded.md`
3. **Follow these steps in order**:
- [ ] Load the ad
- [ ] Register for ad event callbacks
- [ ] Add a UI element to view the ad for a reward
- [ ] Show the ad
- [ ] Verify the implementation