SIGN IN SIGN UP

feat(ads): fire reward-verification tracking events from the poll (#3884)

<!-- Thank you for contributing to Purchases! Before pressing the
"Create Pull Request" button, please provide the following: -->

### Description

This change introduces a new `RewardedAdTrackingMetadata` class as a way
to pass ad information to the reward polling function - and so to make
it possible to _actually_ track the lifecycle of rewarded ads.

The metadata is optional and it is driving if the tracking is happening
or not (someone can simply omit it like today to not have tracking).

<!-- Describe your changes in detail -->

<!-- Please describe in detail how you tested your changes -->

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes the reward-verification poll path and ties it to ad analytics,
but optional metadata and default-null preserve existing callers;
mis-typed metadata could skew event attribution.
> 
> **Overview**
> **Reward polling can now emit ad lifecycle analytics** when callers
pass optional **`RewardedAdTrackingMetadata`** (network, mediator,
format, placement, ad unit, impression id). **`pollRewardVerification`**
and **`awaitPollRewardVerification`** accept this metadata; omitting it
keeps today’s behavior with **no reward-tracking events**.
> 
> During a tracked poll, **`Purchases`** fires **`AdTracker`** events:
earned-unverified at start, then verified / per-grant granted /
failed-to-verify based on the poll **`Outcome`**. **`NoReward`** does
not produce a granted event. Poll **cancellation** still propagates
**`CancellationException`** but records a failed-to-verify with a
**Cancelled** reason when metadata was provided.
> 
> Internal **`Outcome.Failed`** cases now map to
**`AdRewardFailureReason`** for analytics, including a new
**`Cancelled`** failure type. Public API surface and AdMob integration
tests were updated for the expanded **`pollRewardVerification`**
signature (**`AdCaptureMethod.MANUAL`** on manual polls).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
5559b3b96dd41122c2527b2e67c85b8f59484693. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
P
Peter Porfy committed
74585720ce2683992417059212b1fc87a5aa17d9
Parent: 0610106
Committed by GitHub <noreply@github.com> on 8/18/2026, 1:30:28 PM