SDKs

Kotlin SDK

Copy page

The Kotlin SDK provides UI components and API helpers to integrate Bible content into Android applications with minimal setup.

Installation with Gradle

Add the SDK as a dependency in Android Studio:

1. In your project-level settings.gradle.kts, ensure mavenCentral() is included in the repositories block:

Code
pluginManagement {
    repositories {
        google()
        mavenCentral()        
    }
}

2. In your app-level build.gradle.kts, add the dependency:

Code
dependencies {
    implementation("com.youversion.platform:platform-core:1.+")
    // if you choose to point to 1.0.0 only, you can set it to that specific version
    // or use 1.+ to get the latest minor upgrades as they release 
    // or even 1.0.+ to get the latest patches
}

3. Sync your project with Gradle files by clicking File → Sync Project with Gradle Files in Android Studio.

Configure the SDK

Sign up at platform.youversion.com to get your free App Key.

Call YouVersionPlatform.configure once during application startup to configure it with your App Key. A common pattern is to perform the configuration inside your Application class.

Code
import android.app.Application
import com.youversion.platform.YouVersionPlatformConfiguration

class SampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        YouVersionPlatformConfiguration.configure(
            context = this,
            appKey = "YOUR_APP_KEY_HERE"
        )
    }
}

Make sure to register your Application class in your AndroidManifest.xml:

Code
<application
    android:name=".SampleApp"
    ...>
</application>

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.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.

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. 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.BibleReference
import com.youversion.platform.ui.views.text.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.BibleReference
import com.youversion.platform.ui.views.text.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.BibleReference
import com.youversion.platform.ui.views.text.BibleText

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

For longer passages, wrap BibleText in a verticalScroll.

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.YouVersionApi
import com.youversion.platform.votd.YouVersionVerseOfTheDay

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

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
                )
            }
        )
    }
}

Example code

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