Skip to main content

Installation

Requirements​

  • iOS 15.0 or newer deployment target.
  • Xcode 16.4 or newer, building to an iPhone or iPhone Simulator destination. We've verified 16.4, 26.0 through 26.6, and 27.2. 0.3.1 needs Xcode 27 — see Known issues.
  • Python 3.9 or newer — for the one-time setup script. macOS ships with it.
  • GitHub repository access. Genies invites you to geniespartnersdk-ios and geniesnafsdk-ios; accept both before you start.

1. Set up package access​

The SDK ships from private GitHub repositories, so Xcode needs credentials before it can resolve the package. A setup script handles that in one command — you don't need to configure SSH keys or hand-write a ~/.netrc.

Create a token. On GitHub, make a classic personal access token with the repo scope at github.com/settings/tokens.

GitHub shows the token once and never again. Save it somewhere you'll still have it later — a password manager is ideal. You'll want it again to set up another machine or to configure CI, and the only alternative is generating a new one.

Download the script. Grab genies-setup.py from the latest release while signed into GitHub, or use the copy Genies sent you. There's nothing to clone or unpack, and no Python packages to install.

Run it from wherever you downloaded it, and paste the token at the hidden prompt:

python3 genies-setup.py ios

The script identifies your GitHub account, confirms you can reach both repositories, downloads a private binary to prove asset access actually works, and only then writes the credentials to ~/.netrc with owner-only permissions. Unrelated ~/.netrc entries are left alone. If a check fails, nothing is written.

Your token stays yours

Never send the token to Genies and never commit it. Setup prompts for it on every run rather than reusing whatever is already on disk — paste the same token again, or a new one to rotate. The script refuses to take a token as a command-line argument.

2. Add the package in Xcode​

File → Add Package Dependencies, then:

  1. Paste https://github.com/genies-sdk/geniespartnersdk-ios into the search field at the top right.
  2. Set Dependency Rule to Exact Version, and enter 0.3.2.
  3. Click Add Package and let Xcode resolve. The first fetch pulls NAF and LiveKit as well.
  4. Xcode then shows Choose Package Products. Check GeniesPartnerSDK and GeniesPartnerSDKNAF, and set the target for each to your app.

The product list appears only once resolution succeeds. If you never reach step 4, the problem is likely package access — see Known issues.

The package offers two products, and most apps add both:

ProductWhat it carries
GeniesPartnerSDKThe Auth, Inventory, and Notifications modules.
GeniesPartnerSDKNAFAvatar conveniences and chat, bridging the modules to NAF.

NAF resolves automatically either way — the Partner SDK pins the NAF version it was built against, so you don't choose it yourself. See How it fits together for when you'd want one and not the other.

If you generate your project, the package looks like this:

packages:
GeniesPartnerSDK:
url: https://github.com/genies-sdk/geniespartnersdk-ios
exactVersion: 0.3.2

targets:
YourApp:
dependencies:
- package: GeniesPartnerSDK
product: GeniesPartnerSDK
- package: GeniesPartnerSDK
product: GeniesPartnerSDKNAF

On CI​

The script won't prompt without an interactive terminal. Supply the token through the environment instead:

GENIES_SDK_TOKEN=<token> python3 genies-setup.py ios --non-interactive

Known issues​

Building 0.3.1 with Xcode 26 or earlier. 0.3.1 is verified only on Xcode 27. Earlier versions stop with one of these:

  • 'NAFLiveKitAudioAnchors' initializer is inaccessible due to 'private' protection level — NAF's chat transport, in GeniesPartnerSDKNAF.
  • missing required module 'CLiveKitProto' — Xcode 16, with either product.
  • expected '{' in enum in a NAFKitUI interface — Xcode 26.3 or earlier.

Update to 0.3.2 or newer, which builds on Xcode 16.4 and later.

unexpectedly did not find the new dependency in the package graph. Xcode lists the repositories it's fetching and then fails without naming the one it couldn't read. It means your credentials don't cover something in the graph — usually an invitation you haven't accepted yet, or a token that has expired or lost its repo scope. Accept both invitations, run the setup script again, then reset caches and resolve.

Missing package product 'GeniesPartnerSDK', or a resolve that keeps failing after you've fixed the cause. Configure credentials before Xcode first resolves and it shouldn't come to this. Once a failed resolve is cached, work up from the cheapest fix:

  1. File → Packages → Reset Package Caches, then File → Packages → Resolve Package Versions.
  2. If that doesn't clear it, quit Xcode, delete ~/Library/Developer/Xcode/DerivedData, reopen, and resolve again. Deleting DerivedData underneath a running Xcode is what produces missing-product errors, so resolve once more after reopening.

Forcing resolution from the command line makes Xcode use system Git and ~/.netrc:

xcodebuild -resolvePackageDependencies \
-project YourApp.xcodeproj \
-scheme YourApp \
-scmProvider system \
-packageAuthorizationProvider netrc

this SDK is not supported by the compiler. The full error names the Swift version the binary was built with against the version you're running. We've seen this clear with a package cache reset, so try that before going looking for a matching toolchain.

An older project pinned to an SSH package URL. Token setup configures HTTPS only. If your project still resolves git@github.com:…, switch the package URL to the https:// form above — a PAT alone can't satisfy an SSH dependency.

Intel simulator slices. The package ships arm64 simulator slices. On an Intel Mac, exclude x86_64 for simulator builds:

settings:
base:
"EXCLUDED_ARCHS[sdk=iphonesimulator*]": x86_64

Next steps​

GitHub package access is separate from runtime configuration — your app still needs the environment and the app ID Genies issued you.

The fastest way to see all of it working is genies-sdk-sandbox-ios, a complete sample app. It's private like the SDK repositories — ask Genies for access if you don't have it — and it builds on the package access you just set up. Open that first; the Quick Start then walks the same path call by call for your own app.