YouVersion Platform SDK for Swift

https://github.com/youversion/platform-sdk-swift
Admin
A Swift SDK for integrating with the YouVersion Platform, enabling display of Bible content and user...
Tokens:14,919
Snippets:105
Trust Score:6.5
License:Apache-2.0
Update:10 months ago
Show doc for...
Tokens:
Raw
### Embed Full Bible Reader Component with SwiftUI

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Demonstrates how to embed the `BibleReaderView` SwiftUI component to provide a full Bible reading experience. This example sets a specific starting reference (John 1) and includes an app name and a sign-in message for users. It's presented within a TabView.

```swift
import SwiftUI
import YouVersionPlatform

struct AppView: View {
    var body: some View {
        TabView {
            BibleReaderView(
                reference: BibleReference(versionId: 111, bookUSFM: "JHN", chapter: 1),
                appName: "My Bible App",
                signInMessage: "Sign in to sync your highlights and notes across devices."
            )
            .tabItem {
                Label("Bible", systemImage: "book.closed.fill")
            }
        }
    }
}
```

--------------------------------

### Conventional Commit Message Examples (Bash)

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Examples of commit messages following the Conventional Commits specification, demonstrating how 'feat', 'fix', and 'BREAKING CHANGE' impact version bumps. Also shows usage with scopes.

```bash
# Patch release (1.0.0 → 1.0.1)
git commit -m "fix: resolve crash on iPad when opening reader"

# Minor release (1.0.0 → 1.1.0)
git commit -m "feat: add dark mode support to reader"

# Major release (1.0.0 → 2.0.0)
git commit -m "feat: redesign Bible reader API

BREAKING CHANGE: BibleReader.open() now returns async Result<Void, Error>"

# With scope
git commit -m "fix(reader): correct verse highlighting behavior"
```

--------------------------------

### Use Bible Version Repository with Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Demonstrates how to use the BibleVersionRepository for cached Bible version data. It shows loading a version, creating a BibleReference, getting a display title for a reference, and converting a passage string to a BibleReference. Requires the YouVersionPlatform library.

```swift
import YouVersionPlatform

func useBibleVersionRepository() async throws {
    // Repository provides caching for better performance
    let repository = BibleVersionRepository.shared

    // Load version (cached after first fetch)
    let version = try await repository.version(withId: 206)
    print("Loaded: \(version.title)")

    // Create reference and get display title
    let reference = BibleReference(
        versionId: 206,
        bookUSFM: "PSA",
        chapter: 23,
        verse: 1
    )

    let displayTitle = version.displayTitle(
        for: reference,
        includesVersionAbbreviation: true
    )
    print("Display: \(displayTitle)")
    // Output: "Psalm 23:1 MSG"

    // Convert passage ID to reference
    if let ref = version.reference(with: "JHN.3.16") {
        print("Converted: \(ref.debugDescription)")
    }
}
```

--------------------------------

### Add YouVersionPlatform SDK using CocoaPods

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

Guides users to integrate the YouVersion Platform SDK into their projects using CocoaPods. This involves adding the 'YouVersionPlatform' pod to the project's Podfile.

```ruby
pod 'YouVersionPlatform', '~> 1.0'
```

--------------------------------

### Swift Package Manager Dependency

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Example of how to declare a dependency on the platform-sdk-swift package in Swift Package Manager, referencing a specific version tag.

```swift
.package(url: "https://github.com/YouVersion/platform-sdk-swift.git", from: "1.0.0")
```

--------------------------------

### Display Verse of the Day Component with SwiftUI

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Shows how to display the Verse of the Day (VOTD) using the VotdView SwiftUI component. Examples include using the default version and specifying a particular Bible version ID. The component can be styled with padding and corner radius.

```swift
import SwiftUI
import YouVersionPlatform

struct VotdDisplayView: View {
    var body: some View {
        VStack {
            // Default VOTD (uses version 111 - NIV)
            VotdView()
                .frame(height: 300)
                .cornerRadius(12)
                .padding()

            // VOTD with specific Bible version
            VotdView(bibleVersionId: 206)  // The Message
                .frame(height: 300)
                .cornerRadius(12)
                .padding()
        }
    }
}
```

--------------------------------

### Get Specific Bible Version Details with Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Fetches detailed information for a specific Bible version, including its title, abbreviation, text direction, copyright, and a list of available books with their USFM codes and chapter counts. It also checks for the availability of specific book codes. Requires the YouVersionPlatform library.

```swift
import YouVersionPlatform

func loadVersionDetails() async throws {
    // Fetch complete version data including book structure
    let version = try await YouVersionAPI.Bible.version(versionId: 111)

    print("Version: \(version.title)")
    print("Abbreviation: \(version.abbreviation)")
    print("Text direction: \(version.textDirection ?? "ltr")")
    print("Copyright: \(version.copyright ?? "Not specified")")

    // Access available books
    if let books = version.books {
        print("\nAvailable books: \(books.count)")
        for book in books {
            print("  \(book.name) (\(book.usfm))")
            if let chapters = book.chapters {
                print("    Chapters: \(chapters.count)")
            }
        }
    }

    // Check if specific book is available
    if version.bookCodes.contains("GEN") {
        print("\nGenesis is available in this version")
    }
}
```

--------------------------------

### Initialize YouVersion Platform SDK

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Configures the YouVersion Platform SDK with your unique application key. This is a mandatory step before using any SDK features. Ensure you replace 'your_app_key_here' with your actual key obtained from the YouVersion Platform website.

```swift
import SwiftUI
import YouVersionPlatform

@main
struct MyApp: App {
    init() {
        // Configure with your API key from https://platform.youversion.com/
        YouVersionPlatform.configure(appKey: "your_app_key_here")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

--------------------------------

### Create and Push Git Tag

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Creates a Git tag for the specified version and pushes all tags to the origin repository.

```git
git tag 1.2.3
git push origin main --tags
```

--------------------------------

### Implement Sign In with YouVersion SDK (Swift)

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

This snippet demonstrates how to set up and use the YouVersion SDK for user sign-in within an iOS application. It involves creating a presentation context provider, storing a strong reference to it, and utilizing the `SignInWithYouVersionButton` with an asynchronous task to handle the sign-in process. The SDK manages access token storage and persistence across app launches.

```swift
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 your SwiftUI view's header:
@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)
        }
    }
}

```

--------------------------------

### Run Swift SDK Tests

Source: https://github.com/youversion/platform-sdk-swift/blob/main/CONTRIBUTING.md

Instructions for running the SDK's unit tests using either Xcode's graphical interface or the command line via the `swift test` command.

```bash
# Run tests via Xcode
# Select the YouVersionPlatformPackageTests scheme and press Cmd+U

# Or via command line
swift test
```

--------------------------------

### Create and Manipulate Bible References in Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Demonstrates how to create Bible references for single verses, ranges, and full chapters using `BibleReference`. It also shows how to parse USFM strings, convert references to USFM format, check for overlaps, and merge adjacent or overlapping references.

```swift
import YouVersionPlatform

// Single verse reference
let john316 = BibleReference(
    versionId: 111,  // NIV version ID
    bookUSFM: "JHN",
    chapter: 3,
    verse: 16
)

// Verse range reference
let psalm23 = BibleReference(
    versionId: 111,
    bookUSFM: "PSA",
    chapter: 23,
    verseStart: 1,
    verseEnd: 6
)

// Full chapter reference
let genesis1 = BibleReference(
    versionId: 111,
    bookUSFM: "GEN",
    chapter: 1
)

// Parse USFM string to reference
if let reference = BibleReference.unvalidatedReference(
    with: "JHN.3.16",
    versionId: 111
) {
    print("Parsed reference: (reference.debugDescription)")
    // Output: bible111__JHN.3.16
}

// Convert reference to USFM format
let usfm = john316.asUSFM
// Returns: "JHN.3.16"

// Check if references overlap
let reference1 = BibleReference(versionId: 111, bookUSFM: "PSA", chapter: 23, verseStart: 1, verseEnd: 3)
let reference2 = BibleReference(versionId: 111, bookUSFM: "PSA", chapter: 23, verseStart: 2, verseEnd: 5)
if reference1.overlaps(with: reference2) {
    print("References overlap")
}

// Merge adjacent or overlapping references
let merged = BibleReference.referencesByMerging(references: [reference1, reference2])
// Returns: [BibleReference(PSA.23.1-5)]
```

--------------------------------

### Configure YouVersion Platform SDK in Swift

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

Initializes the YouVersion Platform SDK with your unique app key. This configuration must be done during your application's initialization process to enable SDK functionalities.

```swift
import SwiftUI
import YouVersionPlatform

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

--------------------------------

### Implement User Sign-In with YouVersion in SwiftUI

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

This SwiftUI view provides a sign-in interface using YouVersion's authentication flow. It utilizes `SignInWithYouVersionButton` and handles user session state. Dependencies include SwiftUI, AuthenticationServices, and YouVersionPlatform. It allows users to sign in with specified permissions and displays user details upon successful authentication.

```swift
import SwiftUI
import AuthenticationServices
import YouVersionPlatform

struct LoginView: View {
    @State private var contextProvider = ContextProvider()
    @State private var isSignedIn = false
    @State private var errorMessage: String?

    var body: some View {
        VStack(spacing: 20) {
            if isSignedIn {
                Text("Successfully signed in!")
                    .font(.headline)

                if let userId = YouVersionAPI.Users.currentUserId {
                    Text("User ID: \(userId)")
                }

                if let name = YouVersionAPI.Users.currentUserName {
                    Text("Name: \(name)")
                }

                if let email = YouVersionAPI.Users.currentUserEmail {
                    Text("Email: \(email)")
                }

                Button("Sign Out") {
                    Task { @MainActor in
                        YouVersionAPI.Users.signOut()
                        isSignedIn = false
                    }
                }
                .buttonStyle(.bordered)
            } else {
                SignInWithYouVersionButton(
                    shape: .capsule,
                    mode: .full,
                    isStroked: true
                ) {
                    Task {
                        do {
                            let result = try await YouVersionAPI.Users.signIn(
                                permissions: [.profile, .email],
                                contextProvider: contextProvider
                            )
                            isSignedIn = true
                            print("Access token: \(result.accessToken)")
                            print("Permissions granted: \(result.permissions)")
                        } catch {
                            errorMessage = error.localizedDescription
                            print("Sign in error: \(error)")
                        }
                    }
                }

                if let errorMessage {
                    Text("Error: \(errorMessage)")
                        .foregroundColor(.red)
                }
            }
        }
        .padding()
        .onAppear {
            isSignedIn = YouVersionAPI.isSignedIn
        }
    }
}

// Context provider for authentication session
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
    }
}
```

--------------------------------

### Check Authentication Status with YouVersionPlatform SDK

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Demonstrates how to check the user's authentication status using the YouVersionPlatform SDK. It includes both a synchronous check for the access token and an asynchronous check that can refresh the token. It also shows how to retrieve user details like ID, name, email, and profile picture URL if the user is authenticated.

```swift
import YouVersionPlatform

func checkAuthenticationStatus() async {
    // Synchronous check (doesn't refresh token)
    if YouVersionAPI.isSignedIn {
        print("User has access token")
    }

    // Async check (refreshes token if needed)
    if await YouVersionAPI.hasValidToken() {
        print("User has valid access token")

        // Access user information
        if let userId = YouVersionAPI.Users.currentUserId {
            print("User ID: \(userId)")
        }

        if let userName = YouVersionAPI.Users.currentUserName {
            print("User name: \(userName)")
        }

        if let email = YouVersionAPI.Users.currentUserEmail {
            print("Email: \(email)")
        }

        if let profilePicture = YouVersionAPI.Users.currentUserProfilePicture {
            print("Profile picture URL: \(profilePicture)")
        }
    }
}
```

--------------------------------

### Display Bible Widget using SwiftUI and YouVersionPlatform

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Shows how to integrate Bible content into a SwiftUI view using the BibleWidgetView. Supports displaying a single verse or a range of verses. Requires SwiftUI and the YouVersionPlatform SDK.

```swift
import SwiftUI
import YouVersionPlatform

struct WidgetExampleView: View {
    var body: some View {
        VStack(spacing: 20) {
            // Single verse widget
            BibleWidgetView(
                reference: BibleReference(
                    versionId: 111,
                    bookUSFM: "PHP",
                    chapter: 4,
                    verse: 13
                )
            )
            .frame(height: 200)
            .cornerRadius(12)
            .shadow(radius: 5)

            // Verse range widget
            BibleWidgetView(
                reference: BibleReference(
                    versionId: 206,
                    bookUSFM: "PSA",
                    chapter: 23,
                    verseStart: 1,
                    verseEnd: 3
                )
            )
            .frame(height: 250)
            .cornerRadius(12)
            .shadow(radius: 5)
        }
        .padding()
    }
}
```

--------------------------------

### Embed Simple Bible Reader Component with Default Reference

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Illustrates how to use the `BibleReaderView` SwiftUI component with default settings. This allows the reader to open to the user's last read position or a system default if no history exists. It requires an app name and a sign-in message.

```swift
import SwiftUI
import YouVersionPlatform

struct SimpleBibleReader: View {
    var body: some View {
        // Opens to user's last read position or default
        BibleReaderView(
            appName: "My App",
            signInMessage: "Sign in to access your personal Bible study content."
        )
    }
}
```

--------------------------------

### Test commitlint (Bash)

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Bash commands to test the commitlint configuration. The first command validates a correctly formatted commit message, while the second demonstrates an invalid message that should cause commitlint to fail.

```bash
# Valid commit message
echo "feat: add new feature" | npx commitlint

# Invalid commit message (should fail)
echo "invalid message" | npx commitlint
```

--------------------------------

### Configure Custom API Host for YouVersion SDK

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Allows customization of the API host for the YouVersion Platform SDK, typically used for development or testing with custom API endpoints. It requires both the application key and the custom host address.

```swift
import YouVersionPlatform

@main
struct MyApp: App {
    init() {
        // For development or testing with custom API endpoints
        YouVersionPlatformConfiguration.configure(
            appKey: "your_app_key",
            apiHost: "custom.api.host.com"
        )
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

--------------------------------

### Use Custom Network Configuration with YouVersionPlatform

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Demonstrates how to configure and use a custom URLSession for network requests made by the YouVersionPlatform SDK. This allows for customization of aspects like timeouts and headers. Requires the YouVersionPlatform SDK.

```swift
import YouVersionPlatform

func useCustomURLSession() async throws {
    // Configure custom URL session
    let configuration = URLSessionConfiguration.default
    configuration.timeoutIntervalForRequest = 30
    configuration.timeoutIntervalForResource = 300
    configuration.httpAdditionalHeaders = [
        "User-Agent": "MyApp/1.0"
    ]

    let customSession = URLSession(configuration: configuration)

    // Use custom session with API calls
    let versions = try await YouVersionAPI.Bible.versions(
        forLanguageTag: "eng",
        session: customSession
    )

    let votdData = try await YouVersionAPI.VOTD.verseOfTheDay(
        dayOfYear: 1,
        session: customSession
    )

    print("Fetched \(versions.count) versions and VOTD")
}
```

--------------------------------

### Fetch Available Languages with Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Retrieves a list of all available languages supported by the YouVersion platform. It prints the total count and details for each language, including its ID, name, script, text direction, display names, and default Bible ID. Requires the YouVersionPlatform library.

```swift
import YouVersionPlatform

func loadLanguages() async throws {
    // Get all languages
    let allLanguages = try await YouVersionAPI.Languages.languages()
    print("Total languages: \(allLanguages.count)")

    for language in allLanguages {
        print("\(language.id): \(language.language)")
        print("  Script: \(language.script ?? "default")")
        print("  Direction: \(language.textDirection)")
        print("  Display names: \(language.displayNames)")
        print("  Default Bible ID: \(language.defaultBibleId ?? 0)")
        print()
    }
}
```

--------------------------------

### Handle Authentication Errors using YouVersionPlatform and ASWebAuthenticationSession

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Illustrates how to handle errors that can occur during the user sign-in process using YouVersionPlatform's user authentication flow, which relies on ASWebAuthenticationSession. It specifically catches the case where the user cancels the login and other general authentication errors. Requires the YouVersionPlatform SDK and AuthenticationServices.

```swift
import AuthenticationServices
import YouVersionPlatform

func handleSignInErrors(contextProvider: ASWebAuthenticationPresentationContextProviding) async {
    do {
        let result = try await YouVersionAPI.Users.signIn(
            permissions: [.profile, .email],
            contextProvider: contextProvider
        )
        print("Signed in successfully")
    } catch ASWebAuthenticationSessionError.canceledLogin {
        print("User cancelled the sign in")
    } catch let error as ASWebAuthenticationSessionError {
        print("Authentication error: \(error.localizedDescription)")
    } catch {
        print("Unexpected error: \(error)")
    }
}
```

--------------------------------

### Fetch Multiple Chapters in Parallel with Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Fetches the HTML content for multiple Bible chapters concurrently using a throwing task group. It prints the character count for each fetched chapter. Requires the YouVersionPlatform library.

```swift
import YouVersionPlatform

func fetchMultipleChapters() async throws {
    let references = [
        BibleReference(versionId: 111, bookUSFM: "MAT", chapter: 5),
        BibleReference(versionId: 111, bookUSFM: "MAT", chapter: 6),
        BibleReference(versionId: 111, bookUSFM: "MAT", chapter: 7)
    ]

    // Fetch chapters in parallel
    try await withThrowingTaskGroup(of: (BibleReference, String).self) { group in
        for reference in references {
            group.addTask {
                let content = try await YouVersionAPI.Bible.chapter(reference: reference)
                return (reference, content)
            }
        }

        for try await (reference, content) in group {
            print("\(reference.debugDescription): \(content.count) chars")
        }
    }
}
```

--------------------------------

### Merge and Compare Bible References with Swift SDK

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Demonstrates advanced Bible reference operations using the YouVersion Platform SDK for Swift. This includes checking for overlaps, containment, merging adjacent or overlapping references, and comparing reference order. It relies on the BibleReference class and associated static methods for these operations.

```swift
import YouVersionPlatform

func advancedReferenceOperations() {
    let ref1 = BibleReference(versionId: 111, bookUSFM: "ROM", chapter: 8, verseStart: 1, verseEnd: 5)
    let ref2 = BibleReference(versionId: 111, bookUSFM: "ROM", chapter: 8, verseStart: 4, verseEnd: 10)
    let ref3 = BibleReference(versionId: 111, bookUSFM: "ROM", chapter: 8, verseStart: 15, verseEnd: 20)

    // Check if references overlap
    if ref1.overlaps(with: ref2) {
        print("ref1 and ref2 overlap")
    }

    // Check if one contains another
    let smallRef = BibleReference(versionId: 111, bookUSFM: "ROM", chapter: 8, verse: 3)
    if ref1.contains(with: smallRef) {
        print("ref1 contains the smaller reference")
    }

    // Merge adjacent/overlapping references
    let mergedRefs = BibleReference.referencesByMerging(references: [ref1, ref2, ref3])
    print("Merged into \(mergedRefs.count) reference(s):")
    for ref in mergedRefs {
        print("  \(ref.debugDescription)")
    }
    // Output: bible111__ROM.8.1-10, bible111__ROM.8.15-20

    // Compare references
    let comparison = BibleReference.compare(a: ref1, b: ref3)
    if comparison < 0 {
        print("ref1 comes before ref3")
    }
}
```

--------------------------------

### Customize Bible Text Display in Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Illustrates how to customize the appearance of Bible text using `BibleTextView` with a `BibleTextOptions` object. Options include font family, size, spacing, colors, and rendering of headlines and footnotes.

```swift
import SwiftUI
import YouVersionPlatform

struct CustomBibleView: View {
    var body: some View {
        ScrollView {
            BibleTextView(
                BibleReference(versionId: 206, bookUSFM: "ROM", chapter: 8),
                textOptions: BibleTextOptions(
                    fontFamily: "Georgia",
                    fontSize: 18,
                    lineSpacing: 10,
                    paragraphSpacing: 12,
                    textColor: .primary,
                    wocColor: .red,  // Words of Christ color
                    renderHeadlines: true,
                    renderVerseNumbers: true,
                    footnoteMode: .inline
                )
            )
            .padding()
        }
    }
}
```

--------------------------------

### Publish to CocoaPods Script

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Executes a bash script to publish the project to CocoaPods, requiring the new version number as an argument.

```bash
bash scripts/publish-pods.sh 1.2.3
```

--------------------------------

### Customize Sign-In Button Variations with SwiftUI

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Showcases different configurations for the SignInWithYouVersionButton in SwiftUI. These variations include full button with icon and text, a compact version, and an icon-only option. All buttons require a `onTap` closure for handling the sign-in action.

```swift
import SwiftUI
import YouVersionPlatform

struct SignInButtonExamples: View {
    var body: some View {
        VStack(spacing: 20) {
            // Full button with icon and text
            SignInWithYouVersionButton(
                shape: .capsule,
                mode: .full,
                isStroked: true,
                onTap: { performSignIn() }
            )

            // Compact button
            SignInWithYouVersionButton(
                shape: .rectangle,
                mode: .compact,
                isStroked: false,
                onTap: { performSignIn() }
            )

            // Icon only button
            SignInWithYouVersionButton(
                shape: .rectangle,
                mode: .iconOnly,
                isStroked: true,
                onTap: { performSignIn() }
            )
        }
        .padding()
    }

    func performSignIn() {
        // Sign in implementation
    }
}
```

--------------------------------

### Bible Chapter Content API

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

APIs for fetching the content of Bible chapters in HTML format.

```APIDOC
## Fetch Chapter HTML Content

### Description
Retrieves the HTML content for a specific Bible chapter.

### Method
`GET`

### Endpoint
`/v1/bibles/{versionId}/chapters/{chapterId}` (Conceptual endpoint, SDK handles this)

### Parameters
#### Path Parameters
(Handled by `BibleReference` object in SDK)

#### Query Parameters
(Not applicable)

#### Request Body
(Not applicable)

### Request Example
```swift
let reference = BibleReference(versionId: 111, bookUSFM: "ROM", chapter: 8)
let htmlContent = try await YouVersionAPI.Bible.chapter(reference: reference)
```

### Response
#### Success Response (200)
- **htmlContent** (string) - The HTML content of the chapter, including semantic markup.

#### Response Example
```html
<p>1 In this way, all who are in Christ Jesus are children of God. ...</p>
```

## Fetch Multiple Chapters

### Description
Fetches the HTML content for multiple Bible chapters, allowing for parallel fetching for efficiency.

### Method
`GET` (for each chapter, processed in parallel by SDK)

### Endpoint
N/A (SDK handles parallel requests)

### Parameters
#### Path Parameters
(Handled by `BibleReference` objects in SDK)

#### Query Parameters
(Not applicable)

#### Request Body
(Not applicable)

### Request Example
```swift
let references = [
    BibleReference(versionId: 111, bookUSFM: "MAT", chapter: 5),
    BibleReference(versionId: 111, bookUSFM: "MAT", chapter: 6)
]
// ... (code to process references in parallel)
```

### Response
#### Success Response (200)
- **A collection of HTML content strings**, one for each requested chapter, potentially returned as a tuple `(BibleReference, String)`.

#### Response Example
```
MAT 5: chars: 12345
MAT 6: chars: 10000
```
```

--------------------------------

### Fetch Chapter HTML Content with Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Retrieves the HTML content for a specific Bible chapter using a BibleReference. The HTML includes semantic markup for rendering. Requires the YouVersionPlatform library.

```swift
import YouVersionPlatform

func fetchChapterContent() async throws {
    let reference = BibleReference(
        versionId: 111,
        bookUSFM: "ROM",
        chapter: 8
    )

    // Fetch HTML content for the chapter
    let htmlContent = try await YouVersionAPI.Bible.chapter(reference: reference)
    print("Chapter HTML length: \(htmlContent.count) characters")

    // HTML includes semantic markup for verses, headings, poetry, etc.
    // Can be parsed and rendered with custom logic
}
```

--------------------------------

### Languages API

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

API for fetching information about supported languages.

```APIDOC
## Fetch Available Languages

### Description
Retrieves a list of all languages supported by the YouVersion platform.

### Method
`GET`

### Endpoint
`/v1/languages`

### Parameters
#### Path Parameters
(Not applicable)

#### Query Parameters
(Not applicable)

#### Request Body
(Not applicable)

### Request Example
(No explicit request body for GET)

### Response
#### Success Response (200)
- **Array of Language objects**
  - **id** (integer) - The unique identifier for the language.
  - **language** (string) - The name of the language.
  - **script** (string) - The script used for the language (e.g., "Latn", "Cyrl").
  - **textDirection** (string) - The text direction (e.g., "ltr", "rtl").
  - **displayNames** (object) - An object containing localized display names for the language.
  - **defaultBibleId** (integer) - The ID of the default Bible version for this language.

#### Response Example
```json
[
  {
    "id": 1,
    "language": "English",
    "script": "Latn",
    "textDirection": "ltr",
    "displayNames": {"en": "English"},
    "defaultBibleId": 111
  }
]
```
```

--------------------------------

### Test semantic-release Dry-Run (Bash)

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Command to perform a dry-run of semantic-release. This allows you to see what version would be released and what changes would be made without actually publishing anything.

```bash
npx semantic-release --dry-run
```

--------------------------------

### Bible Versions API

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

APIs for fetching Bible versions and their details.

```APIDOC
## Fetch Available Bible Versions

### Description
Retrieves a list of all available Bible versions or versions for a specific language.

### Method
`GET`

### Endpoint
`/v1/bibles` (for all versions)
`/v1/bibles?language=<BCP 47 tag>` (for specific language)

### Parameters
#### Query Parameters
- **language** (string) - Optional - The BCP 47 language tag to filter versions (e.g., "eng").

### Request Example
(No explicit request body for GET)

### Response
#### Success Response (200)
- **Array of Bible Version objects**
  - **id** (integer) - The unique identifier for the Bible version.
  - **title** (string) - The full title of the Bible version.
  - **abbreviation** (string) - The abbreviated name of the Bible version.
  - **languageTag** (string) - The BCP 47 tag for the language of the version.
  - **organizationId** (integer) - The ID of the organization that provides this version.

#### Response Example
```json
[
  {
    "id": 111,
    "title": "The Message",
    "abbreviation": "MSG",
    "languageTag": "eng",
    "organizationId": 1
  }
]
```

## Get Specific Bible Version Details

### Description
Fetches detailed information for a specific Bible version, including its book structure and available books.

### Method
`GET`

### Endpoint
`/v1/bibles/{versionId}`

### Parameters
#### Path Parameters
- **versionId** (integer) - Required - The unique identifier for the Bible version.

#### Request Body
(Not applicable for this endpoint)

### Request Example
(No explicit request body for GET)

### Response
#### Success Response (200)
- **Bible Version object**
  - **id** (integer) - The unique identifier for the Bible version.
  - **title** (string) - The full title of the Bible version.
  - **abbreviation** (string) - The abbreviated name of the Bible version.
  - **textDirection** (string) - The text direction (e.g., "ltr", "rtl").
  - **copyright** (string) - The copyright information for the version.
  - **books** (array) - An array of book objects available in this version.
    - **name** (string) - The name of the book.
    - **usfm** (string) - The USFM code for the book.
    - **chapters** (array) - An array of chapter numbers for the book.
  - **bookCodes** (array) - An array of book USFM codes available in this version.

#### Response Example
```json
{
  "id": 111,
  "title": "The Message",
  "abbreviation": "MSG",
  "textDirection": "ltr",
  "copyright": "© 2002 by Eugene H. Peterson",
  "books": [
    {
      "name": "Genesis",
      "usfm": "GEN",
      "chapters": [1, 2, 3, ...]
    }
  ],
  "bookCodes": ["GEN", "EXO", ...]
}
```

## Access Bible Version from Repository

### Description
Provides methods to access Bible versions using a repository, which includes caching for improved performance. Allows getting version details, creating references, and converting between formats.

### Method
`GET` (for `version(withId:)`)
`N/A` (for reference creation and conversion methods)

### Endpoint
N/A (Repository methods are called locally)

### Parameters
#### Path Parameters
(Not applicable)

#### Query Parameters
(Not applicable)

#### Request Body
(Not applicable)

### Request Example
```swift
let repository = BibleVersionRepository.shared
let version = try await repository.version(withId: 206)
let reference = BibleReference(versionId: 206, bookUSFM: "PSA", chapter: 23, verse: 1)
let displayTitle = version.displayTitle(for: reference, includesVersionAbbreviation: true)
```

### Response
#### Success Response (200)
- **Bible Version object** (for `version(withId:)`)
- **String** (for `displayTitle`)
- **BibleReference object** (for `reference(with:)`)

#### Response Example
```
Loaded: The Living Bible
Display: Psalm 23:1 LB
Converted: BibleReference(versionId: 206, bookUSFM: "JHN", chapter: 3, verse: 16)
```
```

--------------------------------

### Lint CocoaPods Spec

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Validates the syntax and correctness of CocoaPods spec files to ensure they are ready for publishing.

```bash
pod spec lint *.podspec
```

--------------------------------

### Display Bible Chapter in SwiftUI

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

Renders an entire Bible chapter using `BibleTextView`. By specifying only the `versionId`, `bookUSFM`, and `chapter`, the component displays all verses within that chapter.

```swift
import YouVersionPlatform

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

--------------------------------

### Fetch Bible Versions with Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Loads all available Bible versions and filters them by a specific language tag (BCP 47). It prints the total count and details of English versions. Requires the YouVersionPlatform library.

```swift
import YouVersionPlatform

func loadBibleVersions() async throws {
    // Get all Bible versions
    let allVersions = try await YouVersionAPI.Bible.versions()
    print("Total versions available: \(allVersions.count)")

    // Get versions for a specific language (BCP 47 tag)
    let englishVersions = try await YouVersionAPI.Bible.versions(
        forLanguageTag: "eng"
    )

    for version in englishVersions {
        print("\(version.id): \(version.title) (\(version.abbreviation))")
        print("  Language: \(version.languageTag)")
        print("  Organization: \(version.organizationId ?? 0)")
    }
}
```

--------------------------------

### Generate SSH Key Pair (Bash)

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Command to generate an Ed25519 SSH key pair for use with GitHub Actions and semantic-release. The generated keys are named 'deploy_key' and 'deploy_key.pub'.

```bash
ssh-keygen -t ed25519 -C "github-actions-semantic-release" -f deploy_key -N ""
```

--------------------------------

### Test Version Update Script (Bash)

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Bash command to test the `update-pod-versions.sh` script. This script is used to update all podspec files to a specified version. The `--dry-run` flag ensures no actual changes are made, only simulated.

```bash
# Test updating to version 1.2.3 (won't actually publish)
bash scripts/update-pod-versions.sh 1.2.3
```

--------------------------------

### Display Interactive Bible Text with Verse Selection in SwiftUI

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

This SwiftUI view allows users to interact with Bible text, enabling verse selection and displaying footnotes. It utilizes the `BibleTextView` component from the YouVersion Platform SDK. Dependencies include SwiftUI and YouVersionPlatform. It takes a `BibleReference` and `BibleTextOptions` as input and handles verse taps to manage selections or display footnotes.

```swift
import SwiftUI
import YouVersionPlatform

struct InteractiveBibleView: View {
    @State private var selectedVerses: Set<BibleReference> = []
    @State private var showFootnotes = false
    @State private var currentFootnotes: [BibleFootnote] = []

    var body: some View {
        VStack {
            BibleTextView(
                BibleReference(versionId: 111, bookUSFM: "MAT", chapter: 5),
                textOptions: BibleTextOptions(fontSize: 16),
                selectedVerses: $selectedVerses,
                onVerseTap: { reference, actionType, footnotes in
                    if actionType == "footnote" {
                        currentFootnotes = footnotes
                        showFootnotes = true
                    } else {
                        if selectedVerses.contains(reference) {
                            selectedVerses.remove(reference)
                        } else {
                            selectedVerses.insert(reference)
                        }
                    }
                }
            )
            .padding()

            if !selectedVerses.isEmpty {
                Text("Selected \(selectedVerses.count) verse(s)")
                    .padding()
            }
        }
        .sheet(isPresented: $showFootnotes) {
            VStack {
                Text("Footnotes")
                    .font(.headline)
                ForEach(currentFootnotes, id: \.reference) { footnote in
                    Text(footnote.text)
                        .padding()
                }
            }
        }
    }
}
```

--------------------------------

### Handle API Errors with YouVersionPlatform

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Demonstrates robust error handling for API requests made through the YouVersionPlatform SDK. It specifically catches common YouVersionAPIError types like missing authentication, insufficient permissions, network failures, and invalid responses, along with a general error catch-all. Requires the YouVersionPlatform SDK.

```swift
import YouVersionPlatform

func handleAPIErrors() async {
    do {
        let versions = try await YouVersionAPI.Bible.versions()
        print("Success: \(versions.count) versions")
    } catch YouVersionAPIError.missingAuthentication {
        print("Error: App key not configured")
        print("Call YouVersionPlatform.configure(appKey:) at app startup")
    } catch YouVersionAPIError.notPermitted {
        print("Error: Invalid app key or insufficient permissions")
        print("Check your app key at https://platform.youversion.com/")
    } catch YouVersionAPIError.cannotDownload {
        print("Error: Network request failed")
        print("Check internet connection")
    } catch YouVersionAPIError.invalidResponse {
        print("Error: Unexpected server response")
    } catch {
        print("Error: \(error.localizedDescription)")
    }
}
```

--------------------------------

### Display Basic Bible Text in Swift

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Shows how to display a basic Bible verse using the `BibleTextView` SwiftUI component. It requires a `BibleReference` object to specify the scripture to be displayed. The content is scrollable.

```swift
import SwiftUI
import YouVersionPlatform

struct MyBibleView: View {
    var body: some View {
        ScrollView {
            BibleTextView(
                BibleReference(versionId: 111, bookUSFM: "JHN", chapter: 3, verse: 16)
            )
            .padding()
        }
    }
}
```

--------------------------------

### Git Commit Changes

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Adds all changes to the staging area and commits them with a conventional commit message, including the release version and a skip CI flag.

```git
git add .
git commit -m "chore(release): 1.2.3 [skip ci]"
```

--------------------------------

### Add YouVersionPlatform SDK using Swift Package Manager

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

Instructions to add the YouVersion Platform SDK to your Xcode project via Swift Package Manager. This involves adding the Git repository URL to your project's package dependencies.

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

--------------------------------

### Display Bible Verse in SwiftUI

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

Renders a specific Bible verse using the `BibleTextView` component. Requires a `BibleReference` object specifying the version, book, chapter, and verse.

```swift
import YouVersionPlatform

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

--------------------------------

### Display Bible Verse Range in SwiftUI

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

Displays a range of Bible verses using `BibleTextView`. This allows for rendering multiple consecutive verses by providing `verseStart` and `verseEnd` in the `BibleReference`.

```swift
import YouVersionPlatform

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

--------------------------------

### Retrieve CocoaPods Trunk Token (Bash)

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Bash commands to retrieve the CocoaPods trunk session token. The first command uses grep to find the token in the ~/.netrc file, while the second command fetches it directly using 'pod trunk me'.

```bash
# Get your token from ~/.netrc after registering
cat ~/.netrc | grep cocoapods.org

# Or get it from CocoaPods trunk
pod trunk me
```

--------------------------------

### Display Verse of the Day with YouVersion SDK (SwiftUI)

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

This code demonstrates how to display the Verse of the Day (VOTD) in a SwiftUI application using the YouVersion Platform SDK. It shows two approaches: using the built-in `VotdView` component for a quick integration, and fetching VOTD data programmatically for custom UI implementations. The latter involves calculating the day of the year and calling `YouVersionAPI.VOTD.verseOfTheDay`.

```swift
import YouVersionPlatform

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

// Or to 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

```

--------------------------------

### Fetch Verse of the Day Data Manually

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Provides a Swift function to manually fetch Verse of the Day (VOTD) data. This involves calculating the current day of the year and then calling the `YouVersionAPI.VOTD.verseOfTheDay` method. It also demonstrates how to retrieve the Bible version and format the VOTD reference.

```swift
import YouVersionPlatform

func fetchVerseOfTheDay() async throws {
    // Calculate current day of year
    let calendar = Calendar.current
    guard let dayOfYear = calendar.ordinality(of: .day, in: .year, for: Date()) else {
        throw URLError(.badURL)
    }

    // Fetch VOTD data
    let votdData = try await YouVersionAPI.VOTD.verseOfTheDay(
        dayOfYear: dayOfYear
    )

    print("VOTD Passage ID: \(votdData.passageId)")
    print("VOTD Image URL: \(votdData.image?.url ?? "No image")")

    // Load the Bible version to convert passage ID to reference
    let version = try await BibleVersionRepository.shared.version(withId: 111)
    if let reference = version.reference(with: votdData.passageId) {
        print("VOTD Reference: \(reference.debugDescription)")
        print("Display title: \(version.displayTitle(for: reference, includesVersionAbbreviation: true))")
    }
}
```

--------------------------------

### Integrate Bible Reader View in Swift App

Source: https://github.com/youversion/platform-sdk-swift/blob/main/README.md

Embeds the `BibleReaderView` component into your Swift application, providing a full Bible reading experience. It accepts parameters for the app name and a message displayed upon user sign-in.

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

--------------------------------

### Generate Swift SDK Code Coverage Report

Source: https://github.com/youversion/platform-sdk-swift/blob/main/CONTRIBUTING.md

Commands to generate a local code coverage report for the Swift SDK using `xcodebuild`. This involves enabling code coverage during the test execution and then viewing the results within Xcode's Report Navigator.

```bash
# Run tests with coverage enabled
xcodebuild \
  -scheme YouVersionPlatform \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  -derivedDataPath DerivedData \
  -enableCodeCoverage YES \
  test

# View coverage in Xcode
# Open the Report Navigator (Cmd+9) and select the test run to see coverage details
```

--------------------------------

### Filter Languages by Country using YouVersionPlatform

Source: https://context7.com/youversion/platform-sdk-swift/llms.txt

Fetches available Bible languages for a specific country using its ISO 3166-1 alpha-2 code. It demonstrates how to iterate through the results and access language details like display names. Requires the YouVersionPlatform SDK.

```swift
import YouVersionPlatform

func loadLanguagesByCountry() async throws {
    // Get languages used in a specific country (ISO 3166-1 alpha-2 code)
    let usLanguages = try await YouVersionAPI.Languages.languages(country: "US")

    print("Languages available in United States: \(usLanguages.count)")

    for language in usLanguages {
        print("\(language.language) (\(language.id))")
        if let displayName = language.displayNames["en"] {
            print("  English name: \(displayName)")
        }
    }

    // Example for other countries
    let deLanguages = try await YouVersionAPI.Languages.languages(country: "DE")
    print("\nLanguages in Germany: \(deLanguages.count)")
}
```

--------------------------------

### Bypass Commitlint

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Temporarily bypasses the commit message format checks enforced by Commitlint. This should be used with caution.

```git
git commit --no-verify
```

--------------------------------

### Update Pod Versions Script

Source: https://github.com/youversion/platform-sdk-swift/blob/main/RELEASING.md

Executes a bash script to update CocoaPods versions. It takes the new version number as an argument.

```bash
bash scripts/update-pod-versions.sh 1.2.3
```
Tokens:
Raw