Yandex Mobile Ads SDK 8

AI Migration Agent Instructions for the Yandex Mobile Ads SDK

Efficient Migration Strategy

General StrReplace Rules

To avoid tool errors when modifying files:

1. Include surrounding context: Add 1-2 lines before/after for unique matching.
2. Match exact whitespace: Preserve all indentation, spaces, newlines exactly.
3. One logical change per operation: Don't combine multiple unrelated edits.
4. Use unique anchors: Include unique variable/method names or comments.
5. Verify uniqueness: Ensure pattern matches only ONE location in file.
6. Mark manual changes: Whenever you add new code, layouts, or modify logic during the migration, ALWAYS add a comment // FIXME_SDK8: Auto-generated during migration, please review. (or <!-- FIXME_SDK8: Auto-generated during migration, please review. --> in XML) to indicate that this code was auto-generated and requires manual review.

Migration Sequence:

STEP 0: Update Yandex Ads SDK dependencies

Use latest available versions in repositories :

• Core SDK: https://repo.maven.apache.org/maven2/com/yandex/android/mobileads/
• Mediation bundle: https://repo.maven.apache.org/maven2/com/yandex/android/mobileads-mediation/
• Mediation adapters: https://repo.maven.apache.org/maven2/com/yandex/ads/mediation/

STEP 1: Identify Application Package (MANDATORY - CANNOT SKIP)

Read the app module's Gradle build script and find the namespace value (e.g., "com.yandex.ads.sample").

The build script may use either Gradle DSL — do NOT assume .kts:

• Kotlin DSL: app/build.gradle.kts — namespace = "com.yandex.ads.sample"
• Groovy DSL: app/build.gradle — namespace "com.yandex.ads.sample" or namespace = "com.yandex.ads.sample"

Many projects (including Capacitor / hybrid wrappers) use the Groovy build.gradle. Check which file actually exists in the app module before reading it.

If namespace is absent (older AGP), fall back to the applicationId in the same file or the package attribute in app/src/main/AndroidManifest.xml.

CRITICAL: Any import starting with this namespace is application code, NOT SDK code. NEVER replace imports that start with the application namespace.

STEP 2: Bulk Import Replacement

Replace SDK imports ONE BY ONE using bulk find-and-replace (e.g., one command per import). Only process lines that do NOT start with application namespace.

How to replace imports:

• Extract the old and new package/class paths from the Complete Package Structure (SDK 8) and Class Mapping tables below.
• Replace imports ONE AT A TIME with surrounding context.
• Include a blank line or the next import for context to ensure uniqueness.
• Never replace multiple imports in one operation or combine with code changes.

Use IDE's "Replace in Path" feature or command-line tools (sed, PowerShell, etc.)

STEP 3: Bulk Simple API & Removed Classes Replacement

Replace simple class/method names ONE BY ONE using bulk find-and-replace (e.g., one command per API):

How to replace APIs/Classes:

• Replace ONE method call or class name at a time.
• Include surrounding code (variable declaration, next line, type declaration, assignment) for context.
• Preserve original variable names.

Replace patterns:

• MobileAds.initialize → YandexAds.initialize
• AdRequestConfiguration.Builder → AdRequest.Builder
• ClosableBannerAdEventListener → BannerAdEventListener
• MobileInstream → YandexInstreamAds
• BannerAdSize.stickySize → BannerAdSize.sticky
• BannerAdSize.inlineSize → BannerAdSize.inline

Use IDE's "Replace in Path" feature or command-line tools (sed, PowerShell, etc.)

Optional: If possible, perform STEP 2 and STEP 3 in parallel in one response (both commands are independent). If not, perform sequentially.

Do not start the build.

STEP 4: Replace Native Templates

NativeBannerView (with NativeTemplateAppearance) was a ready-made template removed in SDK 8. The SDK now requires a custom native ad view: NativeAdView as the root container + NativeAdViewBinder to bind assets to child views.

Ready-to-use replacement: The Yandex Mobile Ads public sample (YandexMobileAdsExample) provides a complete drop-in implementation. Read the following files from the sample and create them in the partner's project, replacing the sample package com.yandex.ads.sample with the app namespace from STEP 1:

• app/src/main/java/com/yandex/ads/sample/nativeads/NativeAdBannerView.kt — a custom FrameLayout that wires up all native ad asset views via NativeAdViewBinder
• app/src/main/java/com/yandex/ads/sample/common/RatingView.kt — a RatingBar that implements the SDK's Rating interface; place it alongside NativeAdBannerView.kt and update its package
• app/src/main/res/layout/native_banner_ad_view.xml — the full XML layout; update the RatingView class reference to match the new package

Add //FIXME(SDK8): Auto-generated during migration, please review. to the top of each copied Kotlin file.

Migration Actions:

1. Extract customizations first: Search for NativeTemplateAppearance, ButtonAppearance, TextAppearance, ImageAppearance, RatingAppearance, SizeConstraint usages and app:appearance in XML. Note the values — you will apply them to the new layout in step 3.
2. Delete old appearance builder code: Remove all usages of the builders listed above after extracting the values.
3. Apply customizations to native_banner_ad_view.xml: For each value extracted in step 1, set the equivalent XML attribute on the corresponding view. If app:appearance="@style/..." was used, open that style to extract values first.

4. Replace NativeBannerView in XML with NativeAdBannerView (using the partner's app package). Remove the app:appearance attribute. Keep android:id and all layout parameters.
5. Update Kotlin/Java code:
   • Replace nativeBannerView.setAd(nativeAd) → nativeBannerView.bindNativeAd(nativeAd)
   • Add nativeBannerView.release() before each new load and in onDestroy()

Do not start the build.

STEP 5: First Build to Identify Complex Cases

Explain to user: build needed to identify complex migration cases.

Only after completing STEP 1-4, start the fast compilation check:

./gradlew compileDebugSources 2>&1 | tee build.log

Important: This is the first build run before iterative fixes.

STEP 6: Iterative Fixes & Builder Patterns (apply_diff)

For each compilation error:

1. Read the error from the build log (do not restart the build)
2. Verify that the error is related to Yandex Mobile Ads SDK classes. Do NOT attempt to fix unrelated application errors.
3. Use apply_diff to fix it.
4. Fix ALL SDK-related errors from the build log, then rebuild once to verify.

Optional: If fixes are in different files and don't depend on each other, you can perform multiple apply_diff operations in parallel in one response. Important: Do not rebuild after every 5-10 fixes. Fix all SDK-related errors from the current build log, then rebuild once.

Complex cases (require apply_diff):

• Listener refactoring:
  1. Remove setAdLoadListener() call (with context).
  2. Update loadAd() to include listener parameter (with context).
  3. Remove interface implementation from class declaration (if needed).
  4. Convert listener to lambda/object (separate operation).
• AdRequest.Builder with adUnitId parameter:
  • Old: AdRequestConfiguration.Builder().setParameters(...).build()
  • New: AdRequest.Builder(adUnitId).setParameters(...).build()
  • Extract adUnitId from setAdUnitId() call or banner setup. Remove setAdUnitId() call after migration.
• AdTargeting extraction:
  • Old: AdRequest.Builder().setAge(25).setGender(Gender.MALE)
  • New: AdRequest.Builder(id).setTargeting(AdTargeting.Builder().setAge(25).setGender(Gender.MALE).build())
  • Move .setAge(), .setGender(), .setLocation() to AdTargeting.Builder().
• Result.Success/Failure handling.

STEP 7 : Verify success build and fix issues

Iterate assemble application until success build, fix found issues between builds.

(Optional) Check if the user's project uses this specific mediation adapters (mobileads-google, mobileads-mytarget, mobileads-extras):

• minSdk 23 — Only required if the user includes specific mediation adapters (e.g. mobileads-google, mobileads-mytarget, mobileads-extras). If they use these adapters and minSdk is lower than 23, warn them that a manifest merger failure will occur and suggest raising it to 23. Do not force this if they don't use these adapters.
• Kotlin 2.1.0+ — Recommended if transitive dependencies ship Kotlin 2.1 metadata (which causes errors with 1.8 compilers). If the user upgrades Kotlin to 2.0+
• Compose, if Kotlin 2.1 is updated , ensure they use the plugin.compose compiler plugin instead of the old composeOptions { kotlinCompilerExtensionVersion = ... }.

Do not automatically edit these Gradle settings unless the user explicitly agrees or encounters a build error related to them.

Tool Usage Rules:

Recommended Approach (speeds up work):

1. Use sed for bulk replacements (imports, simple APIs), but apply them ONE BY ONE (one pattern per command).
2. Group changes: first process imports (one by one), then simple APIs (one by one).
3. Start the compilation check only after bulk replacements
4. Use apply_diff only for complex cases
5. Read the build log once, fix several errors, then re-run compilation check

Migrate to Yandex Ads SDK 8

• When I ask to migrate to Yandex Mobile Ads SDK 8, start modifying files immediately in the same response without asking for confirmation.
• Assume Yandex artifact versions in the Gradle build script (build.gradle.kts or Groovy build.gradle) are already set by the user. Do not change Yandex / mediation dependency coordinates unless the user asks.
• Exception: always run STEP 0 first to check for optional build toolchain updates. Do not force changes unless the user encounters errors.
• Follow the Fast Migration Strategy above to avoid slow iterative approach.

1. Package Import Changes (Most Important)

Some SDK classes were moved to different packages. Ensure all imports match the SDK 8 package layout.

Action:

1. Replace old class imports with their new package locations throughout the codebase
2. After replacing imports, remove all unused/old imports to prevent compilation errors
3. Exception: Only user's application package imports remain unchanged (e.g., com.yourcompany.yourapp.* - this is application code, not SDK)

2. Special Integration Cases

media3.YandexAdsLoader:

• See Complete Package Structure → row Instream Media3 (ExoPlayer) and Class Mapping → Instream ExoPlayer/Media3 ads insertion and Instream Ad Request (constructor argument type for the loader).

Custom Player Implementations:

• If implementing InstreamAdPlayer, add new required methods:
  • supportedMimeTypes: List<String>
  • bindPlayerView(container: FrameLayout)

Complete Package Structure (SDK 8)

All SDK imports must use com.yandex.mobile.ads.* prefix:

Class Mapping

Method Mapping

Property & Type Changes

Privacy & Consent Methods

Removed APIs & Alternatives

Listener Refactoring Patterns

Pattern 1: Interstitial/Rewarded/AppOpen Load Listener

Migration Steps:

1. Remove setAdLoadListener(this) or setAdLoadListener(listener) call
2. Remove interface implementation from class declaration (if class implements listener)
3. Pass listener as second parameter to loadAd(request, listener)
4. Convert listener to object expression or lambda if needed
5. Cancellation / detach: setAdLoadListener is removed, so a setAdLoadListener(null) call (typically used to detach the listener and cancel loading / avoid stale callbacks, e.g. in onDestroy) has NO loadAd argument to move into. Replace it with loader.cancelLoading(). Do not silently drop it — dropping it changes cleanup behavior and leaves the removed method as a compile error.

Pattern 2: Native Ad Load Listener

Migration Steps:

1. Remove setNativeAdLoadListener(listener) call
2. Update loadAd() to accept two parameters: loadAd(request, listener)
3. Cancellation / detach: setNativeAdLoadListener is removed, so a setNativeAdLoadListener(null) call (typically used to detach the listener and cancel loading / avoid stale callbacks, e.g. in onDestroy) has NO loadAd argument to move into. Replace it with loader.cancelLoading(). Do not silently drop it — dropping it changes cleanup behavior and leaves the removed method as a compile error. (Same applies to NativeBulkAdLoader/SliderAdLoader with setNativeBulkAdLoadListener(null)/setSliderAdLoadListener(null).)

Pattern 3: Instream Ad Load Listener

Migration Steps:

1. Remove setInstreamAdLoadListener(listener) call
2. Pass listener directly to loadAd(request, listener) (method renamed: loadInstreamAd → loadAd; context is no longer passed, loader holds it internally)
3. Update error parameter type from String to InstreamAdRequestError
4. Use error.description to get error message
5. Cancellation / detach: setInstreamAdLoadListener is removed, so a setInstreamAdLoadListener(null) call (typically used to detach the listener and cancel loading / avoid stale callbacks, e.g. in onDestroy) has NO loadAd argument to move into. Replace it with loader.cancelLoading(). Do not silently drop it — dropping it changes cleanup behavior and leaves the removed method as a compile error.

Pattern 4: Banner Event Listener

Migration Steps:

1. Change listener type from ClosableBannerAdEventListener to BannerAdEventListener
2. Remove onAdClosed() method override completely
3. Extract business logic from override fun onAdClosed() to a separate method (e.g., fun onAdClosed())
4. Find the exact place in the application code where onAdClosed() was previously being called and insert the call to your new method there.
5. Add a // FIXME_SDK8: onAdClosed logic migrated from SDK 7.x - verify invocation point comment at the new call site.

Instream SDK Migration to SDK 8

Instream Package Changes

Instream Method Changes

Instream Player Interface Updates

InstreamAdPlayer interface has new required methods:

• override val supportedMimeTypes: List<String> - return list of supported MIME types
  • Use constants from InstreamAdMimeTypes: MP4, WEBM, DASH, HLS, etc.
  • If constant not available, fallback to string literal
• override fun bindPlayerView(container: FrameLayout) - add your player view to the provided container with MATCH_PARENT layout params

Interface Signature Changes

Banner Event Listener

• Removed: onAdClosed() method

Interstitial/Rewarded/AppOpen Load Listener

• Changed: Pass listener directly to loadAd() instead of setAdLoadListener()

Native Ad Load Listener

• Changed: Pass listener directly to loadAd() instead of setNativeAdLoadListener()

Instream Ad Load Listener

• Changed: onInstreamAdFailedToLoad(reason: String) → onInstreamAdFailedToLoad(error: InstreamAdRequestError)

Instream Ad Break Event Listener

• Renamed: InrollEventListener → InstreamAdBreakEventListener
• Renamed methods: onInrollPrepared() → onInstreamAdBreakPrepared(), etc.
• Changed: onInrollError(reason: String) → onInstreamAdBreakError(reason: String)

AI Migration Principles

1. Preserve Logic: Make changes only related to Yandex Mobile Ads SDK upgrade to SDK 8. Do not change business logic.
2. Preserve Names: Keep variable names, method names (except SDK API)
3. Preserve Order: Keep code order unless API requires change
4. Extract Values: When transforming, extract actual values (like adUnitId) and reuse them
5. Combine Calls: When setter + method pattern found, combine into single method call
6. Update Types: When type changes (String → NativeAdWarning), update variable type and access
7. Handle Java: Use new ClassName() { ... } for anonymous classes in .java files, not Kotlin's object :
8. Simplify Queues: Replace Instream queue providers with direct list filtering
9. Optional Players: Consider using null for Instream player parameters when SDK default is acceptable
10. Import Cleanup: After migration, remove ALL old imports and add correct com.yandex.mobile.ads.* imports

Version Info

• Source: SDK 7.x
• Target: SDK 8
• Updated: March 2026
• Package Structure Change: Added March 2026
• Complete Interface Documentation: Added March 2026