iOS quickstart

Connect your first iOS app

Send your first event from an iOS app and verify it in Pharen. Individuals in the United States can explore the demo and check availability for private iOS testing with invented data. Organization approval unlocks test and live keys.

Building for Android? The Android SDK is in private beta.

Evaluate Pharen with a coding agent

Open Integrate your app. The console provides setup instructions for your organization. Request private testing using the steps below. Continue with a private Debug build when the request offers access.

  1. Ask the developer to sign in to the CLI and confirm the organization, Xcode target and bundle ID. If .pharen.yml points to a different organization or app, pause and ask which scope to use. From the project folder, run the command below with the confirmed IDs and use lowercase for the bundle ID. If it exits with code 3 and prints a browser link, ask the developer to open it and confirm the evaluation. Run the printed resume command with --no-login in the same project and CLI sign-in.
  2. Before fetching the SDK, ask the developer to review the license and have an authorized representative accept it for organizational use. Follow the Debug wiring below. Verify that Git ignores the local key file and keep the key value out of logs and chat.
  3. Use the app’s consent flow. With the tester’s feedback consent, build Debug and ask them to send an invented report with a distinct title from a device they control. In the console’s Feedback page, check the same organization and app for a matching report and build in the evaluation environment.
bash
pharen setup ios --evaluation --org YOUR_ORGANIZATION_ID --app YOUR_BUNDLE_ID --no-login

The console can provide a prompt scoped to your organization. For approved organizations, continue with guided CLI setup below.

Wire an evaluation build in Xcode

SDK license. Before obtaining or using the SDK, read its proprietary license (Schedule A, Part C) and the LICENSE.md and LEGAL-TERMS.txt supplied with your selected release. For organizational use, an authorized representative should agree through onboarding or arrange written acceptance with [email protected]. Automated package resolution is not a record of that agreement.

  1. Open Integrate your app. For a new app, use the terminal setup command to register it and request a key. For a registered app, use the manual key command. Follow any browser confirmation and rerun the manual command to save the key if prompted. Once the CLI saves the key, add PharenSDK from https://github.com/pharen-ai/pharen-sdk-swift.git at version 2.1.0 or later. Update the package in Xcode if it resolves an older version. If an XcodeGen spec pins an older version exactly, update its requirement before regenerating the project.
  2. Include the generated Config/Pharen.xcconfig in the app’s existing Debug build settings. Set PharenIngestKey to $(PHAREN_INGEST_KEY) in Info.plist. If Xcode generates the plist, add a source plist with this entry and set the target’s Info.plist File for Debug. Commit shared build wiring and keep the key in the ignored Config/Pharen.local.xcconfig.
  3. Use the app’s consent flow. For a fresh feedback-only evaluation, start the SDK after the tester grants feedback consent. If the app already starts Pharen, update that call to use the tester’s consent and skip crash reporting for this test.
swift
import PharenSDK

#if DEBUG
// Run after the tester grants feedback consent.
Pharen.start(granting: [.content]) { config in
    config.crashReporting.enabled = false
}
#endif

Run Debug on a device you control, shake to open Feedback, and send an invented report. Check that it arrives in Feedback for the same organization and app. To inspect evaluation data with an agent, use browser approval.

Guided CLI setup

These steps are for approved organizations. If approval is pending, open Integrate your app in the console.

  1. Install the CLI, then run setup from the folder containing your Xcode project.
  2. Follow the sign-in link and confirm the app. The CLI writes the build configuration.
  3. Approve the edits for XcodeGen or follow the manual Xcode steps below. Then start the SDK.
bash
npm install -g @pharen-ai/cli
# From the folder containing your Xcode project
pharen setup ios --no-lane

--no-lane keeps this setup focused on the SDK. To also set up a release lane, run pharen setup ios without it. The CLI reference explains the options.

Already wired? Start the SDK and set consent.

Manual Xcode setup for approved organizations

1. Add the SDK

SDK license. Before obtaining or using the SDK, read its proprietary license (Schedule A, Part C) and the LICENSE.md and LEGAL-TERMS.txt supplied with your selected release. For organizational use, an authorized representative should agree through onboarding or arrange written acceptance with [email protected]. Automated package resolution is not a record of that agreement.

PharenSDK is distributed with Swift Package Manager (Apple system frameworks — zero third-party dependencies). In Xcode, File → Add Package Dependencies…, or add it to your Package.swift:

swiftPackage.swift
dependencies: [
    .package(url: "https://github.com/pharen-ai/pharen-sdk-swift.git", from: "2.0.0")
]

Then add "PharenSDK" to your app target's dependencies. If an existing project resolves an older version, update the package in Xcode. If it pins a version exactly, change the package requirement to a compatible range first.

2. Get your keys and attach the configuration

If you ran guided setup, use the file it generated. Otherwise, for an approved organization, install the CLI and run the commands below from your Xcode project folder. This registers the app and gets its keys while leaving the Xcode wiring to you.

bash
npm install -g @pharen-ai/cli
pharen setup ios --no-lane --no-wire

The CLI writes Config/Pharen.xcconfig. In Xcode, attach it under Project → Info → Configurations, or include it from your existing build configuration. Debug uses a registered test environment; Release uses live.

textConfig/Pharen.xcconfig (generated)
PHAREN_INGEST_KEY = YOUR-DEVELOPMENT-KEY
PHAREN_INGEST_KEY[config=Debug]   = YOUR-DEVELOPMENT-KEY
PHAREN_INGEST_KEY[config=Staging] = YOUR-STAGING-KEY
PHAREN_INGEST_KEY[config=Release] = YOUR-PRODUCTION-KEY

3. Add the Info.plist entry

Pharen configures itself from your app's Info.plist — no config code. The key points at the build setting rather than holding a value, which is what gives each build configuration its own environment:

xmlInfo.plist
<key>PharenIngestKey</key>
<string>$(PHAREN_INGEST_KEY)</string>

setup writes this for you on an XcodeGen project. Add it by hand otherwise — and note the indirection is required, not stylistic: Xcode's INFOPLIST_KEY_* build settings only carry Apple's own keys, so a custom one cannot come from the build configuration directly.

Consent is yours to grant, and setup deliberately won't do it for you — see the next section.

Start the SDK and set consent

One line, as early as possible in your app's lifecycle:

swiftMyApp.swift
import PharenSDK
import SwiftUI

@main
struct MyApp: App {
    init() {
        // Reads PharenIngestKey from Info.plist; you grant what you collect.
        Pharen.start(granting: [.telemetry, .behavioral])
    }

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

Use your app's consent policy to decide when to grant each purpose. telemetry covers crashes, hangs, and performance. behavioral covers sessions, screen views, and custom events. content covers reports and surveys. Without content, the feedback form tells users that feedback is unavailable. The privacy guide explains when to grant purposes at runtime or set them in PharenConsentGrantedAtBuild.

That's the whole install. Pharen.start() installs the crash handlers unless you turned them off, starts a session, and begins delivering events in the background — off the main thread, in batches. If the app is unconfigured it returns nil and installs nothing.

Feedback only

Want the report sheet and nothing else, with your crash and analytics stack staying where it is? Grant content alone and leave the crash handlers uninstalled:

swiftMyApp.swift
// Feedback only: no crash, session or analytics event leaves the device.
Pharen.start(granting: [.content]) { config in
    config.crashReporting.enabled = false   // no crash or error handlers are installed
}

A shake opens the sheet, a person writes, and the only events this app sends are the ones a person sends you: a report (its pictures ride with it, and any reply address follows by its own call), or a survey answer if you serve a survey. The SDK's own requests — fetching its served configuration at launch, looking up a link that opens the app — carry no event. Feedback covers the sheet, what a report carries, and running it beside another crash reporter.

Check that your first event arrived

For an approved organization, run your test or live build and check its first event with the CLI. To verify a private evaluation, check the report in console Feedback.

bash
pharen verify --wait

verify checks the things that otherwise fail in silence — a missing or malformed key, a key whose environment doesn't match its build configuration, a value the // rule truncated, a build configuration file nothing reads, a missing Info.plist entry, and a key that has since been revoked. Every check reports pass, fail, warn, or skipped, so a check that couldn't run says so instead of quietly counting as a pass. It exits non-zero on any failure, so it works as a CI gate too.

--wait then watches for your first event and prints it — including the version and build it came from, so you know it was this build talking. That is the confirmation that the integration is live. Add --environment live to watch a different environment, or --timeout 60s to wait less. An app that granted content alone sends nothing until a person writes to you, so shake the device and send a report before expecting --wait to return.

Connect your agent

For test or live data, create a scoped query key for the app and environment shown in the Integration status URL from pharen verify --wait. Replace test with the environment you verified when it differs.

bash
pharen query-keys create --environment test --app your-app
# then point your MCP client at https://mcp.pharen.ai/mcp with the key

Keep the returned key private. Connect your MCP client with that key, then ask it to call pharen_list_metrics and pharen_apps. For the first local run, ask for the ungrouped events.count total in the same environment. It includes local Debug runs without extra grants. Use Integration status or the CLI receipt to verify the specific build. Customer metrics default to released builds, so they may be empty while a Debug build is sending. No additional read grants are needed.

Client-specific connection commands and the data your agent can read: Connect your agent.

Optional: test crash reporting

To test crash capture for an approved organization, enable crash reporting and grant telemetry in a Debug build. Wire the test to a button:

swift
#if DEBUG
Button("Force a test crash") {
    Pharen.crashTest()   // raises an uncaught exception on purpose
}
#endif

Run the app on a device (not the debugger — an attached debugger catches the signal first), tap the button, and let it crash.

Check the crash after relaunch

Relaunch with telemetry still granted so the SDK can attempt the upload. Check your Pharen console for the crash issue.

Choose your next task