yandexmobile/yandex-ads-sdk-android/migrate-yandex-ads-sdk-from-7-to-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.

1. Replace `NativeBannerView` in XML with NativeAdBannerView (using the partner's app package). Remove the app:appearance attribute. Keep android:id and all layout parameters.
2. 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 — Only required if the user includes specific mediation adapters, and the required level differs per adapter. mobileads-google requires minSdk 24 starting with Yandex Mobile Ads SDK 8.4.0, where it moved to the GMA Next-Gen SDK (it was 23 before). mobileads-extras bundles third-party SDKs that already require minSdk 24. mobileads-mytarget requires minSdk 23. If they use these adapters and minSdk is lower, warn them that a manifest merger failure will occur and suggest raising it accordingly. 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