{"id":46274272,"url":"https://github.com/youversion/platform-sdk-kotlin","last_synced_at":"2026-03-04T04:01:08.634Z","repository":{"id":324132730,"uuid":"1094547616","full_name":"youversion/platform-sdk-kotlin","owner":"youversion","description":"Kotlin SDK for the YouVersion Platform","archived":false,"fork":false,"pushed_at":"2026-02-24T23:10:39.000Z","size":3361,"stargazers_count":6,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-25T02:05:10.695Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/youversion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T21:21:35.000Z","updated_at":"2026-02-24T20:23:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/youversion/platform-sdk-kotlin","commit_stats":null,"previous_names":["youversion/platform-sdk-kotlin"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/youversion/platform-sdk-kotlin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youversion%2Fplatform-sdk-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youversion%2Fplatform-sdk-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youversion%2Fplatform-sdk-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youversion%2Fplatform-sdk-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/youversion","download_url":"https://codeload.github.com/youversion/platform-sdk-kotlin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youversion%2Fplatform-sdk-kotlin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30071670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T03:25:38.285Z","status":"ssl_error","status_checked_at":"2026-03-04T03:25:05.086Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-04T04:01:08.075Z","updated_at":"2026-03-04T04:01:08.626Z","avatar_url":"https://github.com/youversion.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n![Platform Kotlin SDK](./assets/github-kotlin-sdk-banner.png)\n\n![Platform](https://img.shields.io/badge/Platform-Android-green)\n[![License](https://img.shields.io/badge/license-Apache-blue.svg)](LICENSE)\n\n# YouVersion Platform SDK for Kotlin\n\nA Kotlin SDK for integrating with the YouVersion Platform, enabling developers to display Scripture \ncontent and implement user authentication in any Android environment. Multiplatform support is \ncurrently not available.\n\n## Table of Contents\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n  - [Which Modules Do I Need?](#which-modules-do-i-need)\n  - [With Version Catalog](#with-version-catalog)\n  - [Without Version Catalog](#without-version-catalog)\n- [Getting Started](#getting-started)\n- [Usage](#usage)\n  - [Displaying Scripture](#displaying-scripture)\n  - [Displaying Verse of the Day](#displaying-verse-of-the-day)\n  - [Authentication](#authentication)\n- [Sample App](#sample-app)\n- [For Different Use Cases](#-for-different-use-cases)\n- [Contributing](#contributing-starting-early-2026)\n- [Documentation](#documentation)\n- [Support](#support)\n- [License](#license)\n\n    \n\n## Features\n- 📖 **Scripture Display** - Easy-to-use Jetpack Compose components for displaying Bible verses, chapters, and passages with `BibleText`\n- 🔐 **User Authentication** - Seamless \"Sign In with YouVersion\" integration using `SignInWithYouVersionButton`\n- 🌅 **Verse of the Day** - Built-in `VerseOfTheDay` component and API access to VOTD data\n- 🚀 **Modern Kotlin** - Built with coroutines, Jetpack Compose, and Material Theming\n- 💾 **Smart Caching** - Automatic local caching for improved performance\n\n## Requirements\n\n- Android 5.0+\n- Android Studio Narwhal+\n- Kotlin 2.2.0+\n- A YouVersion Platform API key ([Register here](https://platform.youversion.com/))\n\n\n## Installation\n\nBe sure you have `mavenCentral()` in your `repositories` block.\n```kotlin\n// settings.gradle.kts\nrepositories {\n    google()\n    mavenCentral()\n}\n```\n\n### Which Modules Do I Need?\n\nThe Platform SDK is broken into three main modules:\n- `platform-core`: Provides the core functionality for accessing the YouVersion Platform API.\n- `platform-ui`: Provides UI components for displaying Bible content.\n- `platform-reader`: Provides a full Bible Reader experience.\n\n---\n**I want to only access the Bible API's and build my own integrations**\n\nYou will only need `platform-core`.\n\n**I want to display Bible content or authenticate with YouVersion in my app but with my own styling**\n\nYou will need `platform-ui` and `platform-core`.\n\n**I want a full, batteries included, drop-in Bible Reader experience**\n\nYou will need `platform-reader`, `platform-ui`, and `platform-core`.\n\n---\n\nGreat! Now that you know which modules you need, you can proceed with installation.\n\n### With Version Catalog\n\n```toml\n# gradle/libs.versions.toml\n[versions]\nyouVersionPlatform = \"1.0.0\"\n\n[libraries]\nyouversion-platform-core = { module = \"com.youversion.platform:platform-sdk-core\", version.ref = \"youVersionPlatform\" }\nyouversion-platform-ui = { module = \"com.youversion.platform:platform-sdk-ui\", version.ref = \"youVersionPlatform\" }\nyouversion-platform-reader = { module = \"com.youversion.platform:platform-sdk-reader\", version.ref = \"youVersionPlatform\" }\n```\n\n```kotlin\n// app/build.gradle.kts\nimplementation(libs.youversion.platform.core)\nimplementation(libs.youversion.platform.ui)\nimplementation(libs.youversion.platform.reader)\n```\n\n### Without Version Catalog\n\n```kotlin\nval youVersionPlatform = \"1.0.0\"\nimplementation(\"com.youversion.platform:platform-core:$youVersionPlatform\")\nimplementation(\"com.youversion.platform:platform-ui:$youVersionPlatform\")\nimplementation(\"com.youversion.platform:platform-reader:$youVersionPlatform\")\n```\n\n## Getting Started\n\n1. **Get Your API Key**: Register your app with [YouVersion Platform](https://platform.youversion.com/) to acquire an app key\n2. **Configure the SDK**: Add the following to your app's initialization:\n\n```kotlin\nclass MainApplication : Application() {\n    override fun onCreate() {\n        super.onCreate()\n        YouVersionPlatformConfiguration.configure(\n            context = this,\n            appKey = TODO(\"YOUR_APP_KEY_HERE\"),\n        )\n    }\n}\n```\n\n## Usage\n\n### Displaying Scripture\n\nDisplay a single verse:\n```kotlin\n@Composable\nfun Demo() {\n    BibleText(\n        reference = BibleReference(versionId = 3034, bookUSFM = \"JHN\", chapter = 3, verse = 16)\n    )\n}\n```\n\nDisplay a verse range:\n```kotlin\n@Composable\nfun Demo() {\n    BibleText(\n        reference = BibleReference(versionId = 3034, bookUSFM = \"JHN\", chapter = 3, verseStart = 16, verseEnd = 20)\n    )\n}\n```\n\nOr display a full chapter:\n```kotlin\n@Composable\nfun Demo() {\n    BibleText(\n        reference = BibleReference(versionId = 3034, bookUSFM = \"JHN\", chapter = 3)\n    )\n}\n```\n\n\u003e **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.\n\n### Displaying Verse of the Day\n\nUse the built-in VOTD component:\n\n```kotlin\n@Composable\nfun Demo() {\n    CompactVerseOfTheDay()\n    // Or\n    VerseOfTheDay()\n}\n```\n\nOr fetch VOTD data for custom UI:\n\n```kotlin\nsuspend fun fetchVotd(): YouVersionVerseOfTheDay {\n    val dayOfTheYear = Calendar.getInstance().get(Calendar.DAY_OF_YEAR)\n    return YouVersionApi.votd.verseOfTheDay(dayOfTheYear)\n}\n```\n\n### Authentication\n\nIntegrating \"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.\n\n#### 1. Configure the Manifest\n\nTo 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.\n\n```xml\n\u003c!-- AndroidManifest.xml --\u003e\n\u003cactivity\n    android:name=\".MainActivity\"\n    android:exported=\"true\"\u003e\n    \u003c!-- ... existing intent filters --\u003e\n\n    \u003c!-- Handle OAuth callback --\u003e\n    \u003cintent-filter\u003e\n        \u003caction android:name=\"android.intent.action.VIEW\" /\u003e\n        \u003ccategory android:name=\"android.intent.category.DEFAULT\" /\u003e\n        \u003ccategory android:name=\"android.intent.category.BROWSABLE\" /\u003e\n\n        \u003cdata\n            android:scheme=\"youversionauth\"\n            android:host=\"callback\" /\u003e\n    \u003c/intent-filter\u003e\n\u003c/activity\u003e\n```\n\n#### 2. Update Your Main Activity\n\nYour main activity must extend `SignInWithYouVersionActivity`. This allows the SDK to automatically handle the result from the sign-in process.\n\n```kotlin\n// MainActivity.kt\nimport com.youversion.platform.ui.signin.SignInWithYouVersionActivity\n\nclass MainActivity : SignInWithYouVersionActivity() {\n    // ...\n}\n```\n\n#### 3. Add the Sign-In Button to Your UI\n\nUse 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.\n\n- `SignInWithYouVersionPermission.PROFILE`: To access the user's name and profile picture.\n- `SignInWithYouVersionPermission.EMAIL`: To access the user's email address.\n\n```kotlin\n// ProfileScreen.kt\nimport androidx.compose.runtime.Composable\nimport androidx.compose.runtime.getValue\nimport androidx.lifecycle.compose.collectAsStateWithLifecycle\nimport androidx.lifecycle.viewmodel.compose.viewModel\nimport com.youversion.platform.core.users.model.SignInWithYouVersionPermission\nimport com.youversion.platform.ui.signin.SignInViewModel\nimport com.youversion.platform.ui.views.SignInWithYouVersionButton\n\n@Composable\nfun ProfileScreen() {\n    val signInViewModel = viewModel\u003cSignInViewModel\u003e()\n    val state by signInViewModel.state.collectAsStateWithLifecycle()\n\n    if (state.isSignedIn) {\n        Column {\n            Text(\"Welcome, ${state.userName ?: \"User\"}!\")\n            Text(\"Your email is ${state.userEmail ?: \"not available\"}.\")\n            Spacer(modifier = Modifier.height(16.dp))\n            Button(onClick = { signInViewModel.onAction(SignInViewModel.Action.SignOut()) }) {\n                Text(\"Sign Out\")\n            }\n        }\n    } else {\n        SignInWithYouVersionButton(\n            permissions = {\n                setOf(\n                    SignInWithYouVersionPermission.PROFILE,\n                    SignInWithYouVersionPermission.EMAIL\n                )\n            }\n        )\n    }\n}\n```\n\nThat's it. The `SignInViewModel` will automatically update its state, and your UI will recompose to reflect the user's authentication status.\n\n## Sample App\n\nExplore the [examples directory](./examples) for a complete sample app demonstrating:\n- Scripture display with various reference types\n- User authentication flows\n- VOTD integration\n- Best practices for token storage\n\nTo run the sample app:\n1. Open the `platform-sdk-kotlin` directory in Android Studio\n2. Wait for Gradle sync to complete (File → Sync Project with Gradle Files if needed)\n3. Add your API key to `examples/sample-android/src/main/java/com/youversion/platform/MainApplication.kt`\n4. Select `sample-android` from the run configuration dropdown\n5. Create an emulator if needed (Tools → Device Manager → Create Device)\n6. Click Run\n\n## 🎯 For Different Use Cases\n\n### 📱 Kotlin SDK\n\nBuilding an Android application? This Kotlin SDK provides native Jetpack Compose components including `BibleText`, `VerseOfTheDay`, and `SignInWithYouVersionButton` using modern language features.\n\n### 🔧 API Integration\n\nNeed direct access to YouVersion Platform APIs? See [our comprehensive API documentation](https://developers.youversion.com/overview) for advanced integration patterns and REST endpoints.\n\n### 🤖 LLM Integration\n\nBuilding AI applications with Bible content? Access YouVersion's LLM-optimized endpoints and structured data designed for language models. See [our LLM documentation](https://developers.youversion.com/for-llms) for details.\n\n## Contributing (Starting Early 2026)\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to get started.\n\n## Documentation\n\n- [API Documentation](https://developers.youversion.com/overview) - Complete API reference\n- [LLM Integration Guide](https://developers.youversion.com/for-llms) - AI/ML integration docs\n- [Release Process](./RELEASING.md) - Contribution and release guidelines\n- [Sample Code](./examples) - Working examples and best practices\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/youversion/platform-sdk-kotlin/issues)\n- **Questions**: Open a [discussion](https://github.com/youversion/platform-sdk-kotlin/discussions)\n- **Platform Support**: [YouVersion Platform](https://platform.youversion.com/)\n\n## License\n\nThis SDK is licensed under the Apache License 2.0. See [LICENSE](./LICENSE) for details.\n\n---\n\nMade with ❤️ by [YouVersion](https://www.youversion.com)\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouversion%2Fplatform-sdk-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyouversion%2Fplatform-sdk-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouversion%2Fplatform-sdk-kotlin/lists"}