Guides

Migrating to 3.0

Copy page

Version 3.0 of the Kotlin SDK contains breaking changes. Most of them surface as Gradle sync or compile errors, so work through the steps below in order and rebuild after each one.

1. Update the BOM
2. Declare libraries you use directly
3. Update error handling
4. Replace copy() and destructuring
5. Remove references to types and icons that are no longer available

Update the BOM

You're affected if your app uses any SDK module.

Raise the platform-bom version to 3.+. The BOM sets the version of every SDK module, so declare the modules without a version of their own:

build.gradle.kts
dependencies {
    implementation(platform("com.youversion.platform:platform-bom:3.+"))
    implementation("com.youversion.platform:platform-core")
    implementation("com.youversion.platform:platform-ui")
    implementation("com.youversion.platform:platform-reader")
}

Keep only the modules your app uses. If your app pins a version on an individual module, remove it and let the BOM set it, so the modules stay on the same release.

Declare libraries you use directly

You're affected if your app uses Koin, androidx.collection:collection, or the Compose material3, foundation, material-ripple, animation, or animation-core libraries without declaring them directly.

These libraries are no longer exposed through the SDK's compile dependencies. Code that relies on those dependencies stops compiling until you declare them directly. The foundation-layout library remains exposed through platform-ui, so imports such as PaddingValues are unaffected. Add only the libraries your app imports:

build.gradle.kts
dependencies {
    // Replace <compose-bom-version> with the Compose BOM version your app uses
    implementation(platform("androidx.compose:compose-bom:<compose-bom-version>"))
    implementation("androidx.compose.material3:material3")
    implementation("androidx.compose.foundation:foundation")
    implementation("androidx.compose.material:material-ripple")
    implementation("androidx.compose.animation:animation")
    implementation("androidx.compose.animation:animation-core")

    // Not managed by the Compose BOM, so these need their own versions
    implementation("androidx.collection:collection:<collection-version>")
    implementation("io.insert-koin:koin-core:<koin-version>")
}

Update error handling

You're affected if your app checks the reason of a YouVersionNetworkException.

• CANNOT_DOWNLOAD is renamed to REQUEST_FAILED, and INVALID_DOWNLOAD is removed.
• Failed responses now report a more specific reason: RATE_LIMITED and SERVER_ERROR for failures a later retry may fix, and REQUEST_REJECTED for requests the server won't accept.
• Reason is now a class instead of an enum, and more reasons may be added in later releases. A when over reason needs an else branch, and enum members such as name, ordinal, values(), and entries are gone. Use toString() to log a reason.
• Requesting a data exchange token for a user whose sign-in is no longer accepted now fails with MISSING_AUTHENTICATION instead of NOT_PERMITTED. NOT_PERMITTED still means the user hasn't granted the permission.

The following fragments show how to update search error handling. For search, NOT_PERMITTED indicates an app key configuration or access problem. For user-authenticated operations, it can indicate a missing user permission instead.

Before:

Code
when (e.reason) {
    YouVersionNetworkException.Reason.NOT_PERMITTED -> showConfigurationError()
    YouVersionNetworkException.Reason.CANNOT_DOWNLOAD,
    YouVersionNetworkException.Reason.INVALID_DOWNLOAD,
    YouVersionNetworkException.Reason.INVALID_RESPONSE,
    YouVersionNetworkException.Reason.MISSING_AUTHENTICATION -> showUnavailable()
}

After:

Code
when (e.reason) {
    YouVersionNetworkException.Reason.NOT_PERMITTED -> showConfigurationError()
    YouVersionNetworkException.Reason.RATE_LIMITED,
    YouVersionNetworkException.Reason.SERVER_ERROR -> showTryAgainLater()
    else -> showUnavailable()
}

See the search guide's error handling section for search failure reasons and how long to wait before retrying.

Replace copy() and destructuring

You're affected if your app calls copy() on an SDK model or destructures one.

SDK models are no longer Kotlin data classes, so they have no copy() or componentN() functions. Value equality is preserved.

Replace destructuring with property access:

Code
// Before
val (id, abbreviation) = version

// After
val id = version.id
val abbreviation = version.abbreviation

Replace copy() by building the new value from the properties you need. For example, to move a BibleReference to another Bible version, where you previously called reference.copy(versionId = newId):

Code
val start = reference.verseStart
val end = reference.verseEnd
val moved =
    if (start != null && end != null) {
        BibleReference(newId, reference.bookUSFM, reference.chapter, start, end)
    } else {
        BibleReference(newId, reference.bookUSFM, reference.chapter)
    }

BibleTextNode.text and BibleTextNode.children are now read-only, and children is a List.

No longer available

You're affected if your app references an SDK type, model constructor, or drawable that is no longer public. The compiler names each one, and the 3.0.0 breaking changes in the changelog list them all.

• Internal types: types that support the SDK's own components, such as HighlightChange, PendingHighlightOperation, and BibleVersionsViewModel.State, are no longer public. Remove references to them.
• Model constructors: your app can no longer construct the models the SDK returns, such as BibleVersion or SearchResults. Types you create as input, such as BibleReference and SearchUserIntent, keep their public constructors.
• Drawables: the SDK no longer ships drawable resources, so if your app references an R.drawable from the SDK, add your own asset instead.