Kotlin SDK

Components

Copy page

The Kotlin SDK provides Jetpack Compose components and API helpers for integrating Bible content into Android applications. Complete the Quick Start before using these examples.

Filter the Bible versions you offer

By default, every version picker in the SDK — in BibleCard and in BibleReader — offers Bible versions in every available language. Two optional configure parameters narrow that list.

Pass permittedLanguageTags to restrict the picker to a set of languages. For example, to make only English versions available:

Code
YouVersionPlatformConfiguration.configure(
    context = this,
    appKey = "YOUR_APP_KEY_HERE",
    permittedLanguageTags = setOf("en"),
)

Tags follow BCP 47 (for example "en" for English, "es" for Spanish). When the resulting list contains versions in only one language, the language button in the version picker is hidden automatically.

Pass permittedVersionIds to restrict the picker to specific Bible versions:

Code
YouVersionPlatformConfiguration.configure(
    context = this,
    appKey = "YOUR_APP_KEY_HERE",
    permittedVersionIds = setOf(12, 111, 1588),
)

IDs are the YouVersion Bible version IDs (for example 111 for NIV, 1588 for AMP). The two filters combine — a version must satisfy both to be shown.

Display Content with BibleCard

The SDK ships with Jetpack Compose components, including BibleCard, which renders a passage given its reference. Provide a BibleReference describing the version, book, and verse range you want to display, and optionally adjust the font size.

Code
import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.youversion.platform.core.bibles.domain.BibleReference
import com.youversion.platform.ui.views.card.BibleCard

@Composable
fun ExampleCardView() {
    BibleCard(
        reference = BibleReference(
            versionId = 3034,
            bookUSFM = "2CO",
            chapter = 1,
            verseStart = 3,
            verseEnd = 4
        ),        
    )
}

@Preview
@Composable
fun ExampleCardViewPreview() {
    ExampleCardView()
}

The card will fetch and format the passage automatically.

Let users switch versions with the version picker

Pass showVersionPicker = true to render a version-picking button in the card's header. Tapping it opens a bottom sheet where the user can pick a different Bible version, and the card re-renders the passage in the selected version automatically.

Code
import androidx.compose.runtime.Composable
import androidx.compose.ui.unit.sp
import com.youversion.platform.core.bibles.domain.BibleReference
import com.youversion.platform.ui.views.card.BibleCard

@Composable
fun ExampleCardView() {
    BibleCard(
        reference = BibleReference(
            versionId = 3034,
            bookUSFM = "2CO",
            chapter = 1,
            verseStart = 3,
            verseEnd = 4
        ),
        fontSize = 16.sp,
        showVersionPicker = true,
    )
}

Provide an optional onVersionChange lambda if you want to react to the user's selection — for example, to persist their preferred version so it can be used as the default the next time the card is shown.

Code
BibleCard(
    reference = BibleReference(
        versionId = 3034,
        bookUSFM = "JHN",
        chapter = 3,
        verse = 16
    ),
    showVersionPicker = true,
    onVersionChange = { version ->
        // Persist version.id, refresh other UI, etc.
    },
)

Display Content with BibleText

Use BibleText when you want inline scripture rendering in your own layouts. Unlike BibleCard this is "merely" the nicely formatted text of the Bible passage: it doesn't include elements to show the verse reference, doesn't show the Bible version's name or its copyright information - you need to provide those separately. See Copyright & Attribution for a complete example that keeps the passage and its version metadata in sync. You can pass a single verse, a verse range, or a full chapter reference.

Single verse

Code
import androidx.compose.runtime.Composable
import com.youversion.platform.core.bibles.domain.BibleReference
import com.youversion.platform.ui.views.BibleText

@Composable
fun SingleVerseView() {
    BibleText(
        reference = BibleReference(
            versionId = 3034,
            bookUSFM = "JHN",
            chapter = 3,
            verse = 16
        )
    )
}

Verse range

Code
import androidx.compose.runtime.Composable
import com.youversion.platform.core.bibles.domain.BibleReference
import com.youversion.platform.ui.views.BibleText

@Composable
fun VerseRangeView() {
    BibleText(
        reference = BibleReference(
            versionId = 3034,
            bookUSFM = "JHN",
            chapter = 3,
            verseStart = 16,
            verseEnd = 20
        )
    )
}

Full chapter

Code
import androidx.compose.runtime.Composable
import com.youversion.platform.core.bibles.domain.BibleReference
import com.youversion.platform.ui.views.BibleText

@Composable
fun ChapterView() {
    BibleText(
        reference = BibleReference(
            versionId = 3034,
            bookUSFM = "JHN",
            chapter = 3
        )
    )
}

For longer passages, wrap BibleText in a verticalScroll.

When the user is signed in and has granted the highlights permission, BibleText also renders their YouVersion highlights behind the verse text, so a custom reading UI stays in sync with BibleReader. See Highlights.

Embed a Full Reader with BibleReader

BibleReader displays a complete Bible reading experience, very similar to the YouVersion Bible app, ready to be added as a tab in your app. It lives in the platform-reader module.

Code
import androidx.compose.runtime.Composable
import com.youversion.platform.reader.BibleReader

@Composable
fun ReaderTab() {
    BibleReader()
}

The sign-in prompt the reader presents to a signed-out user names your app and shows your own reason for asking. Both come from configuration:

Code
YouVersionPlatformConfiguration.configure(
    context = this,
    appKey = "YOUR_APP_KEY_HERE",
    appName = "Your App Name",
    signInPromptMessage = "Sign in to see your **YouVersion** highlights in **Your App Name**",
)

Both parameters are optional. signInPromptMessage supports **bold** markdown. Leave appName out and the prompt names your app by its launcher label — set it when that label is not the name you want a reader to see before granting account access.

Open to a specific passage

Pass a bibleReference to choose where the reader opens:

Code
import androidx.compose.runtime.Composable
import com.youversion.platform.core.bibles.domain.BibleReference
import com.youversion.platform.reader.BibleReader

@Composable
fun ReaderTab() {
    BibleReader(
        bibleReference = BibleReference(
            versionId = 3034,
            bookUSFM = "PSA",
            chapter = 23
        ),
    )
}

Offer your own fonts and a bottom bar

Pass a fontDefinitionProvider to add your own fonts to the reader's font settings sheet, and a bottomBar composable to render your own content beneath the reader — a tab bar, for example.

Code
BibleReader(
    fontDefinitionProvider = myFontDefinitionProvider,
    bottomBar = { MyAppTabBar() },
)

Disabling Sign-In

By default, a signed-out user who taps a verse is prompted to sign in with YouVersion. To suppress all SDK-provided sign-in UI, including that prompt and the header menu's sign-in option, set isSignInEnabled to false during configuration:

Code
YouVersionPlatformConfiguration.configure(
    context = this,
    appKey = "YOUR_APP_KEY_HERE",
    isSignInEnabled = false,
)

When sign-in is disabled, the reader hides the highlight colors rather than offering a control that could never work.

Implement Sign In with YouVersion

If your app needs authenticated user data, use SignInWithYouVersionButton.

1. Configure the redirect in AndroidManifest.xml

Code
<activity
    android:name=".MainActivity"
    android:exported="true">

    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:scheme="youversionauth"
            android:host="callback" />
    </intent-filter>
</activity>

2. Extend SignInWithYouVersionActivity

Code
import com.youversion.platform.ui.signin.SignInWithYouVersionActivity

class MainActivity : SignInWithYouVersionActivity()

3. Add SignInWithYouVersionButton to your UI

Code
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewmodel.compose.viewModel
import com.youversion.platform.core.users.model.SignInWithYouVersionPermission
import com.youversion.platform.ui.signin.SignInViewModel
import com.youversion.platform.ui.views.SignInWithYouVersionButton

@Composable
fun ProfileScreen() {
    val signInViewModel = viewModel<SignInViewModel>()
    val state by signInViewModel.state.collectAsStateWithLifecycle()

    if (state.isSignedIn) {
        Column {
            Text("Welcome, ${state.userName ?: "User"}!")
            Text("Your email is ${state.userEmail ?: "not available"}.")
            Spacer(modifier = Modifier.height(16.dp))
            Button(onClick = { signInViewModel.onAction(SignInViewModel.Action.SignOut()) }) {
                Text("Sign Out")
            }
        }
    } else {
        SignInWithYouVersionButton(
            permissions = {
                setOf(
                    SignInWithYouVersionPermission.PROFILE,
                    SignInWithYouVersionPermission.EMAIL
                )
            }
        )
    }
}

Highlights

Highlights belong to the user's YouVersion account, not to your app. A highlight created in your app appears in the YouVersion Bible app and in any other app the user has granted access to, and highlights the user already made elsewhere appear in yours.

BibleReader provides the full experience with no extra work: tapping a verse opens the verse action sheet with a color picker, choosing a color highlights the selected verses, and choosing the color a verse already has removes the highlight. On dark reader themes the colors are dimmed automatically so the verse text stays readable. BibleText renders the same highlights, so a custom reading UI built on platform-ui stays in sync with the reader.

Highlights are layered across the three modules, so you only need the ones your integration uses:

Module	What it adds
platform-core	The highlights API, the HIGHLIGHTS permission, and the local cache. Enough on its own to read and write highlights.
platform-ui	Highlight rendering behind verse text in BibleText, plus the helpers for requesting the permission.
platform-reader	The verse action sheet color picker, the color palette, and dark-theme dimming.

Highlight permissions

Reading and writing highlights requires the user to be signed in and to have granted SignInWithYouVersionPermission.HIGHLIGHTS. There is no anonymous or app-local highlight, so the permission is only ever obtained through YouVersion sign-in — either bundled into the sign-in request, or added afterwards for a user who is already signed in.

BibleReader asks for it at the moment it is needed, taking one of those two routes:

• A signed-out user is offered sign-in, with the highlights permission included in the requested permissions. The grant rides along with the sign-in.
• A signed-in user who has not granted it yet is shown a confirmation dialog and then the YouVersion permission page. This is the data exchange flow, and it exists so the user does not have to sign in again just to grant one more permission.

Both routes come back through the youversionauth://callback redirect used by sign-in — either as an activity result when the SDK opened the permission page in an Auth Tab, or as a deep link into your SignInWithYouVersionActivity. Either way, highlights only work end to end once your app has completed the Sign In setup: the manifest intent filter and a main activity extending SignInWithYouVersionActivity. Without that setup the grant never reaches the SDK and highlights stay unavailable.

To check whether the permission has been granted:

Code
import com.youversion.platform.core.api.YouVersionApi
import com.youversion.platform.core.users.model.SignInWithYouVersionPermission

val hasHighlightsPermission =
    YouVersionApi.hasPermission(SignInWithYouVersionPermission.HIGHLIGHTS)

Requesting the permission without the reader

If you render highlights with BibleText but do not embed BibleReader, nothing in your app ever asks for the grant — the verse action sheet is the only built-in prompt. Without a request of your own, the user simply never sees their highlights. The same applies to users who signed in before you added highlights: they have no HIGHLIGHTS grant, and nothing will ask them for one.

For a user who is already signed in, request it from Compose with rememberDataExchange. This is a top-up rather than an alternative to signing in — a signed-out user needs SignInWithYouVersionPermission.HIGHLIGHTS included in the sign-in request instead.

Code
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberCoroutineScope
import com.youversion.platform.core.users.model.SignInWithYouVersionPermission
import com.youversion.platform.ui.dataexchange.rememberDataExchange
import kotlinx.coroutines.launch

@Composable
fun AllowHighlightsButton() {
    val requestDataExchange = rememberDataExchange()
    val coroutineScope = rememberCoroutineScope()

    Button(
        onClick = {
            coroutineScope.launch {
                val result = requestDataExchange(setOf(SignInWithYouVersionPermission.HIGHLIGHTS))
                if (result?.grants(SignInWithYouVersionPermission.HIGHLIGHTS) == true) {
                    // The grant is already persisted; highlights load on the next read.
                }
            }
        }
    ) {
        Text("Allow highlights")
    }
}

Outside Compose, use DataExchangeHandler(activityResultRegistry).requestDataExchange(...) directly. Either way the granted permission is persisted for you before the call returns, so a later YouVersionApi.hasPermission(...) reflects it without any extra work. A BibleText already on screen picks up the new grant and loads the user's highlights without being recreated.

Highlights API

Apps using only platform-core can read and write highlights directly through YouVersionApi.highlights. All four calls are suspend functions and require the signed-in user to have granted the highlights permission.

Code
import com.youversion.platform.core.api.YouVersionApi

// Read a chapter's highlights
val highlights = YouVersionApi.highlights.highlights(versionId = 111, passageId = "JHN.3")

// Create, recolor, and remove a highlight on a single verse
YouVersionApi.highlights.createHighlight(versionId = 111, passageId = "JHN.3.16", color = "fffe00")
YouVersionApi.highlights.updateHighlight(versionId = 111, passageId = "JHN.3.16", color = "5dff79")
YouVersionApi.highlights.deleteHighlight(versionId = 111, passageId = "JHN.3.16")

Note that passageId is a chapter for the read call ("JHN.3") but a single verse for the write calls ("JHN.3.16").

Colors are hex strings without a leading #. The palette the reader offers is fffe00 (yellow), 5dff79 (green), 00d6ff (cyan), ffc66f (orange), and ff95ef (pink), matching the Swift SDK.

Error handling

The read and write calls report failure differently, so handle both:

• All four calls throw YouVersionNetworkException with reason NOT_PERMITTED when the user has not granted highlights access. This applies to the whole account rather than to the requested chapter, and the request will not succeed on retry.
• The read call also throws YouVersionNetworkException with reason MISSING_AUTHENTICATION when the request was not authenticated, which a sign-in or token refresh may resolve. A failure is reported rather than an empty chapter so that callers caching the result do not mistake it for the server reporting that the chapter holds no highlights.
• The create, update, and delete calls each return a Boolean. A false return — for an unauthenticated request, for example — means the write did not happen, so check the result and don't rely on try/catch alone.

To call the same endpoints outside the SDK, see the highlights REST API reference.

Display Verse of the Day

Use the built-in Verse of the Day components:

Code
import androidx.compose.runtime.Composable
import com.youversion.platform.ui.views.votd.CompactVerseOfTheDay
import com.youversion.platform.ui.views.votd.VerseOfTheDay

@Composable
fun VerseOfTheDayView() {
    CompactVerseOfTheDay()
    // Or
    VerseOfTheDay()
}

Or fetch Verse of the Day data for custom UI:

Code
import java.util.Calendar
import com.youversion.platform.core.api.YouVersionApi
import com.youversion.platform.core.votd.models.YouVersionVerseOfTheDay

suspend fun fetchVotd(): YouVersionVerseOfTheDay {
    val dayOfYear = Calendar.getInstance().get(Calendar.DAY_OF_YEAR)
    return YouVersionApi.votd.verseOfTheDay(dayOfYear)
}

Example code

See the SampleApp project in the Examples folder to see the above code in action!