Installation

Add NEAR Connect iOS to your project using Swift Package Manager

Swift Package Manager

NEAR Connect iOS is distributed via Swift Package Manager. There are two ways to add it to your project:

Method 1: Xcode UI (Recommended)

The easiest way to add NEAR Connect iOS is through Xcode’s package manager interface:

1. Open Package Dependencies

   In Xcode, go to File > Add Package Dependencies…

2. Enter Repository URL

   Paste the repository URL into the search field:

   https://github.com/frol/near-connect-ios
   

   Press Enter to search for the package.

3. Select Version

   Choose your preferred version rule:

   • Up to Next Major Version: 1.0.0 (recommended)
   • Up to Next Minor Version: 1.0.0
   • Exact Version: Lock to a specific release
   • Branch: Use main for the latest changes

   Using a branch instead of a version tag means your app will get updates automatically, which could include breaking changes. For production apps, always pin to a specific version.

4. Add to Target

   Select the NEARConnect library and add it to your app target.

   Click Add Package to complete the installation.

5. Import the Module

   In your Swift files, import the module:

   import NEARConnect
   

Method 2: Package.swift

If you’re building a Swift package or prefer editing Package.swift directly:

1. Add Package Dependency

   Open your Package.swift file and add NEAR Connect iOS to the dependencies array:

   Package.swift

   // swift-tools-version: 5.9
   
   import PackageDescription
   
   let package = Package(
       name: "YourApp",
       platforms: [
           .iOS(.v16)
       ],
       dependencies: [
           .package(
               url: "https://github.com/frol/near-connect-ios",
               from: "1.0.0"
           )
       ],
       targets: [
           .target(
               name: "YourApp",
               dependencies: [
                   .product(name: "NEARConnect", package: "near-connect-ios")
               ]
           )
       ]
   )
   

   The package name in the URL is near-connect-ios, but the product name you import is NEARConnect.

2. Resolve Dependencies

   Run the following command in your terminal:

   swift package resolve
   

   Or in Xcode: File > Packages > Resolve Package Versions

3. Import the Module

   In your Swift files:

   import NEARConnect
   

Verifying Installation

To verify NEAR Connect iOS is installed correctly, create a simple test:

ContentView.swift

import SwiftUI
import NEARConnect

struct ContentView: View {
    @StateObject private var walletManager = NEARWalletManager()
    
    var body: some View {
        VStack {
            if walletManager.isBridgeReady {
                Text("✅ NEAR Connect is ready!")
            } else {
                Text("⏳ Initializing...")
            }
        }
        .padding()
    }
}

Build and run your app. You should see “NEAR Connect is ready!” appear after a brief initialization period.

The isBridgeReady property indicates when the JavaScript bridge has finished loading. All wallet operations require the bridge to be ready.

Platform Requirements

NEAR Connect iOS requires:

Requirement	Version
iOS	16.0 or later
Swift	5.9 or later
Xcode	16.0 or later

The iOS 16 requirement is due to the use of modern Swift concurrency features and SwiftUI APIs. If you need to support earlier iOS versions, consider using callbacks or older async patterns.

Info.plist Configuration (Optional)

Some NEAR wallets use deep links to return to your app after authentication. To support these flows:

1. Register a Custom URL Scheme

Add a URL scheme to your app’s Info.plist:

Info.plist

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>
        </array>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp</string>
    </dict>
</array>

Replace yourapp with your app’s unique identifier.

2. Handle Incoming URLs

In your app’s main view or scene:

.onOpenURL { url in
    // Handle deep link if needed
    print("Opened URL: \(url)")
}

For most wallets, deep link handling is automatic. You only need custom handling if you’re implementing wallet-specific callback logic.

Troubleshooting

Package Resolution Fails

If Xcode can’t resolve the package:

1. Check your internet connection
2. Verify the repository URL is correct
3. Try File > Packages > Reset Package Caches
4. Check that your Xcode version meets the minimum requirements

Build Errors

If you see compiler errors after adding the package:

• Ensure your project’s iOS deployment target is set to iOS 16.0 or later
• Clean the build folder: Product > Clean Build Folder (⇧⌘K)
• Delete derived data: ~/Library/Developer/Xcode/DerivedData

WebView Not Loading

If the wallet UI doesn’t appear:

• Check the Xcode console for JavaScript errors
• Enable WebView inspection in Safari: Settings > Safari > Advanced > Web Inspector
• Verify your device/simulator has an internet connection (the bridge loads from CDN)

The bridge HTML loads JavaScript from cdn.jsdelivr.net. Ensure your app’s network security settings allow this domain, or consider bundling the JavaScript locally for offline support.

Next Steps

Quick Start Guide

Build your first wallet connection in under 5 minutes

API Reference

Explore the complete NEARWalletManager API