YouVersion Platform SDK for Swift

A Swift SDK for integrating with the YouVersion Platform, to display Bible content and implement user authentication in iOS, iPadOS, and other platforms where Swift can run.

Table of Contents

• Features
• Requirements
• Installation
  • Swift Package Manager
  • CocoaPods
• Getting Started
• Usage
  • Displaying Scripture in SwiftUI
  • Bible Reader
  • Implementing Sign In
  • Fetching User Data
  • Displaying Verse of the Day
• Sample App
• For Different Use Cases
• Documentation
• Contributing
• Support
• License

Features

• 📖 Scripture Display - Easy-to-use SwiftUI components for displaying Bible verses with BibleTextView and BibleCardView
• 📖 Bible Reader - A complete Bible reading experience inside your app with BibleReaderView
• 🔐 User Authentication - Seamless "Sign In with YouVersion" integration using SignInWithYouVersionButton
• 🌅 Verse of the Day - Built-in VotdView component and API access to VOTD data

Requirements

• iOS 17+ / iPadOS 17+
• A YouVersion Platform API key (Register here)

Installation

Swift Package Manager

1. In Xcode, open your app project, then select the menu File → Add Package Dependencies
2. Enter the package URL: https://github.com/youversion/platform-sdk-swift.git
3. Select platform-sdk-swift from the search results.
4. Click Add Package
5. Click Add Package on the next dialog.

Or add it to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/youversion/platform-sdk-swift.git", from: "0.1.0")
]

CocoaPods

Add the following to your Podfile:

pod 'YouVersionPlatform', '~> 1.0'

Then run pod install

Getting Started

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

import SwiftUI
import YouVersionPlatform

@main
struct YourApp: App {
    init() {
        YouVersionPlatform.configure(appKey: "YOUR_APP_KEY_HERE")
    }
    var body: some Scene {...
}

Usage

Displaying Scripture in SwiftUI

Display a single verse:

import YouVersionPlatform

struct DemoView: View {
    var body: some View {
        BibleTextView(
            BibleReference(versionId: 3034, bookUSFM: "JHN", chapter: 3, verse: 16)
        )
    }
}

Display a verse range:

import YouVersionPlatform

struct DemoView: View {
    var body: some View {
        BibleTextView(
            BibleReference(versionId: 3034, bookUSFM: "JHN", chapter: 3, verseStart: 16, verseEnd: 20)
        )
    }
}

Or display a full chapter:

import YouVersionPlatform

struct DemoView: View {
    var body: some View {
        BibleTextView(
            BibleReference(versionId: 3034, bookUSFM: "JHN", chapter: 3)
        )
    }
}

Note: For longer passages, wrap BibleTextView in a ScrollView.

The SDK automatically fetches Scripture from YouVersion servers and maintains a local cache for improved performance.

Bible Reader

Displays a full Bible reading experience, very similar to the YouVersion Bible app, ready to be added as a tab in your app.

    BibleReaderView(
        appName: "Sample App",
        signInMessage: "Sign in to see your YouVersion highlights in this Sample App."
    )

Implementing Sign In

First, create a helper class for presentation context:

import AuthenticationServices

class ContextProvider: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        guard let scene = UIApplication.shared.connectedScenes.first as? UIWindowScene,
              let window = scene.windows.first else {
            return ASPresentationAnchor()
        }
        return window
    }
}

In the header of your SwiftUI view, store a strong reference to the ContextProvider:

@State private var contextProvider = ContextProvider() // Store a strong reference

Add the "Sign In" button to your SwiftUI view:

    SignInWithYouVersionButton {
        Task {
            do {
                let result = try await YouVersionAPI.Users.signIn(
                    permissions: [.profile, .email],
                    contextProvider: contextProvider
                )
                // The user is logged in and you have an access token at result.accessToken!
                // You may now call the YouVersion Platform APIs which require authentication.
            } catch {
                print(error)
            }
        }
    }
}

Note: The SDK stores the access token locally, and persists it across app launches. Deleting or losing the access token is the equivalent of "logging out".

Fetching User Data

Retrieve information about the authenticated user:

// Implementation TBD - this information will be included in response tokens in the future.

Displaying Verse of the Day

Use the built-in VOTD component:

import YouVersionPlatform

struct ContentView: View {
    var body: some View {
        VotdView()
    }
}

Or fetch VOTD data for custom UI:

let dayOfYear = Calendar.current.ordinality(of: .day, in: .year, for: Date())!
let votd = try await YouVersionAPI.VOTD.verseOfTheDay(dayOfYear: dayOfYear)
// Use votd.reference with BibleTextView

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 platform-sdk-swift directory in Xcode
2. Select the SampleApp scheme
3. Build and run on simulator or device

🎯 For Different Use Cases

📱 Swift SDK

Building an iOS or iPadOS application? This Swift SDK provides native SwiftUI components including BibleTextView, VotdView, and SignInWithYouVersionButton with full Swift Package Manager support and modern async/await APIs.

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

Documentation

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

Contributing

We welcome contributions! Please see our Contributing Guide for details on development setup, code style, and the pull request process.

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