YouVersion Platform SDK for Kotlin

A Kotlin SDK for integrating with the YouVersion Platform, enabling developers to display Scripture content and implement user authentication in any Android environment. Multiplatform support is currently not available.

Table of Contents

• Features
• Requirements
• Installation
  • Which Modules Do I Need?
  • With Version Catalog
  • Without Version Catalog
• Getting Started
• Usage
  • Displaying Scripture
  • Displaying Verse of the Day
  • Authentication
• Sample App
• For Different Use Cases
• Contributing
• Documentation
• Support
• License

Features

• 📖 Scripture Display - Easy-to-use Jetpack Compose components for displaying Bible verses, chapters, and passages with BibleText
• 🔐 User Authentication - Seamless "Sign In with YouVersion" integration using SignInWithYouVersionButton
• 🌅 Verse of the Day - Built-in VerseOfTheDay component and API access to VOTD data
• 🚀 Modern Kotlin - Built with coroutines, Jetpack Compose, and Material Theming
• 💾 Smart Caching - Automatic local caching for improved performance

Requirements

• Android 5.0+
• Android Studio Narwhal+
• Kotlin 2.2.0+
• A YouVersion Platform API key (Register here)

Installation

Be sure you have mavenCentral() in your repositories block.

// settings.gradle.kts
repositories {
    google()
    mavenCentral()
}

Which Modules Do I Need?

The Platform SDK is broken into three main modules:

• platform-core: Provides the core functionality for accessing the YouVersion Platform API.
• platform-ui: Provides UI components for displaying Bible content.
• platform-reader: Provides a full Bible Reader experience.

---

I want to only access the Bible API's and build my own integrations

You will only need platform-core.

I want to display Bible content or authenticate with YouVersion in my app but with my own styling

You will need platform-ui and platform-core.

I want a full, batteries included, drop-in Bible Reader experience

You will need platform-reader, platform-ui, and platform-core.

---

Great! Now that you know which modules you need, you can proceed with installation.

With Version Catalog

# gradle/libs.versions.toml
[versions]
youVersionPlatform = "0.7.1"

[libraries]
youversion-platform-core = { module = "com.youversion.platform:platform-sdk-core", version.ref = "youVersionPlatform" }
youversion-platform-ui = { module = "com.youversion.platform:platform-sdk-ui", version.ref = "youVersionPlatform" }
youversion-platform-reader = { module = "com.youversion.platform:platform-sdk-reader", version.ref = "youVersionPlatform" }

// app/build.gradle.kts
implementation(libs.youversion.platform.core)
implementation(libs.youversion.platform.ui)
implementation(libs.youversion.platform.reader)

Without Version Catalog

val youVersionPlatform = "0.7.1"
implementation("com.youversion.platform:platform-core:$youVersionPlatform")
implementation("com.youversion.platform:platform-ui:$youVersionPlatform")
implementation("com.youversion.platform:platform-reader:$youVersionPlatform")

Getting Started

1. Get Your API Key: Register your app with YouVersion Platform to acquire an app key
2. Configure the SDK: Add the following to your app's initialization:

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

Usage

Displaying Scripture

Display a single verse:

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

Display a verse range:

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

Or display a full chapter:

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

Note: For longer passages, wrap BibleText in a verticalScroll. The SDK automatically fetches Scripture from YouVersion servers and maintains a local cache for improved performance.

Displaying Verse of the Day

Use the built-in VOTD component:

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

Or fetch VOTD data for custom UI:

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

Authentication

Integrating "Sign In with YouVersion" is straightforward. The SDK handles the entire authentication flow, including launching the sign-in screen, handling the redirect, and managing tokens.

1. Configure the Manifest

To handle the redirect from the YouVersion authentication, you need to add an intent filter to your main activity in your AndroidManifest.xml file. The SDK will use this to receive the authentication result.

<!-- AndroidManifest.xml -->
<activity
    android:name=".MainActivity"
    android:exported="true">
    <!-- ... existing intent filters -->

    <!-- Handle OAuth callback -->
    <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. Update Your Main Activity

Your main activity must extend SignInWithYouVersionActivity. This allows the SDK to automatically handle the result from the sign-in process.

// MainActivity.kt
import com.youversion.platform.ui.signin.SignInWithYouVersionActivity

class MainActivity : SignInWithYouVersionActivity() {
    // ...
}

3. Add the Sign-In Button to Your UI

Use the SignInWithYouVersionButton composable in your UI. You can use the SignInViewModel to check if the user is already signed in and conditionally display the button.

• SignInWithYouVersionPermission.PROFILE: To access the user's name and profile picture.
• SignInWithYouVersionPermission.EMAIL: To access the user's email address.

// ProfileScreen.kt
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
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
                )
            }
        )
    }
}

That's it. The SignInViewModel will automatically update its state, and your UI will recompose to reflect the user's authentication status.

Sample App

Explore the examples directory for a complete sample app demonstrating:

• Scripture display with various reference types
• User authentication flows
• VOTD integration
• Best practices for token storage

To run the sample app:

1. Open the platform-sdk-kotlin directory in Android Studio
2. Wait for Gradle sync to complete (File → Sync Project with Gradle Files if needed)
3. Add your API key to examples/sample-android/src/main/java/com/youversion/platform/MainApplication.kt
4. Select sample-android from the run configuration dropdown
5. Create an emulator if needed (Tools → Device Manager → Create Device)
6. Click Run

🎯 For Different Use Cases

📱 Kotlin SDK

Building an Android application? This Kotlin SDK provides native Jetpack Compose components including BibleText, VerseOfTheDay, and SignInWithYouVersionButton using modern language features.

🔧 API Integration

Need direct access to YouVersion Platform APIs? See our comprehensive API documentation for advanced integration patterns and REST endpoints.

🤖 LLM Integration

Building AI applications with Bible content? Access YouVersion's LLM-optimized endpoints and structured data designed for language models. See our LLM documentation for details.

Contributing (Starting Early 2026)

See CONTRIBUTING.md for details on how to get started.

Documentation

• API Documentation - Complete API reference
• LLM Integration Guide - AI/ML integration docs
• Release Process - Contribution and release guidelines
• Sample Code - Working examples and best practices

Support

• Issues: GitHub Issues
• Questions: Open a discussion
• Platform Support: YouVersion Platform

License

This SDK is licensed under the Apache License 2.0. See LICENSE for details.

---

Made with ❤️ by YouVersion