Skip to main content
This guide helps you install the Gameball iOS SDK v3.1.1 and prepare your project for integration.
Once installed, you will be ready to initialize the SDK and register customers.

​
1. Requirements

Your project must meet the following minimum requirements:
  • iOS Version: 12.0+
  • Xcode: 12.0+
  • Swift: 5.0+
  • Package Manager: Swift Package Manager (SPM)

​
2. Checklist Before Installation

Before installing the SDK, ensure you have:
  • A Gameball Project Key from your Dashboard
  • Selected your environment (sandbox recommended for testing)
  • A valid bundle identifier for iOS
  • A unique player identifier strategy (user ID, email, UUID, etc.)
  • Swift Package Manager enabled in your project

​
3. Install the SDK

Install the SDK via Swift Package Manager. In Xcode:
  1. Go to File → Add Packages
  2. Enter the repository URL:
https://github.com/gameballers/gameball-ios.git
  1. Select Version 3.1.1 (or Up to Next Major)
  2. Click Add Package

​
4. Import the SDK

In any Swift file where you plan to use Gameball: 
import Gameball

​
5. Verify Installation

Build your project to confirm the SDK was added successfully.

​
Using Xcode

⌘ + B

​
Using terminal

xcodebuild -workspace YourApp.xcworkspace \
           -scheme YourApp \
           -sdk iphonesimulator \
           -configuration Debug build
If your build succeeds, you are ready to initialize the SDK.

​
6. Next Steps

Proceed with:
  • Initialize SDK Connect your app to Gameball using your API key and (optionally) Session Token.
  • Initialize Customer Profile Register and identify your player.

​
7. Troubleshooting

Below are common installation issues and fixes.

​
Problem: “No such module ‘Gameball’”

Fixes:
  • Product → Clean Build Folder (⇧⌘K)
  • Xcode → File → Packages → Reset Package Caches
  • Verify the package is added to your target
  • Restart Xcode

​
Problem: Deployment target or API availability warnings

Fixes:
  • Ensure iOS 12.0+ minimum deployment target
  • Update Info.plist if needed
  • Ensure Xcode 12+ and Swift 5.0+

​
Problem: dyld or framework loading errors

Fixes:
  • Run pod install
  • Remove/re-add the SPM package
  • Delete DerivedData:
rm -rf ~/Library/Developer/Xcode/DerivedData

​
Problem: Package dependency not resolving

Fixes:
  • Confirm you selected 3.1.1 (or newer) in the package dialog
  • Remove and re-add the package in Xcode
  • Verify network connectivity to GitHub

​
8. Debug Logging

The SDK includes built-in debug logging visible in Xcode’s console. Filter logs by typing: 
Gameball
Common categories include:
  • Initialization
  • Network
  • Events
  • Profile
Use this during development to quickly diagnose issues.