Get started

Requirements

• An iOS app targeting iOS 16 or later.

• Xcode with Swift Package Manager. The SDK is distributed as a compiled XCFramework with the AppNorth product.

• An AppNorth account and permission to create or configure a project.

• Your public App ID, server base URL and an allowed origin.

Your app can use SwiftUI or host the SwiftUI views with UIKit. App Store Connect and RevenueCat credentials are separate from SDK configuration.

Create your project

1. Sign in and complete onboarding to create your iOS app project. You can select an App Store app or enter your app’s name.

2. Open the project’s SDK setup screen. For an existing project, open its SDK setup from the dashboard.

3. Copy the public App ID and the installation configuration. Copy setup prompt supplies the project name and App ID to your coding agent.

The public App ID identifies the project receiving feedback. Use the public ID from SDK setup, not the internal project ID in the dashboard URL.

Onboarding creates an allowed localhost origin. For an existing project, check its allowed domains before reusing the example below. origin is a required SDK configuration value sent on writes, even though your product is a native iOS app. It is an anti-abuse signal, not proof of user identity.

Set up with a coding agent

Open your iOS project in your coding agent and paste the setup prompt. The dashboard version already includes your public App ID. The public version below asks for it before configuring the SDK.

The agent should ask where the support or community entry belongs, follow your app’s dependency injection pattern, build the app and verify a real test message. If you use accounts, it also needs an authenticated backend to issue verified identity credentials.

Setup prompt

Copy this prompt into your coding agent. It asks for your App ID; the prompt copied during onboarding fills it in for you.

Integrate AppNorth into my iOS app "ask the developer".
Public App ID: "ask the developer". This is a public identifier, not a secret.

First read https://www.appnorth.app/llms.txt and https://www.appnorth.app/docs/get-started.md. Use https://www.appnorth.app/docs/overview.md for product context. If the App ID says "ask the developer", ask for the public App ID from the project’s SDK setup screen before editing configuration. Never use that placeholder in a shipped app.

1. Inspect the app's architecture, deployment target and dependency setup. AppNorth requires iOS 16 or newer. Before changing navigation, ask me where the feedback/community entry should go.
2. Add the Swift Package https://github.com/victorgxn/appnorth-ios, from version 0.2.0, and link the AppNorth product to the app target. It distributes a compiled XCFramework.
3. Create and retain one AppNorthClient at launch, following the app's dependency injection pattern. Use this documented configuration and SwiftUI entry:

import AppNorth
import SwiftUI

let configuration = try AppNorthConfiguration(
    apiURL: URL(string: "https://www.appnorth.app")!,
    appId: "ask the developer",
    origin: URL(string: "http://localhost")!
)
let client = AppNorthClient(configuration: configuration)

struct FeedbackScreen: View {
    var body: some View {
        AppNorthView(client: client)
    }
}

The current SDK requires origin and sends it on writes. onboarding-created projects allow localhost; verify the allowed origins for an existing project; do not invent a website or remove the required initializer argument. apiURL is the AppNorth server base URL, not a /api/v1 endpoint. If it points to localhost, a physical iPhone needs a reachable server URL.
4. Add the entry where I chose. Use AppNorthView(client: client) for ideas and feedback, or AppNorthChatView(client: client) for the support conversation. Use UIHostingController if the app uses UIKit.
5. If the app has accounts, obtain a short-lived v1 identity credential from its authenticated backend and use AppNorthIdentityCredential(email:expiresAt:signature:) with client.setIdentityCredential(_:). Call client.clearIdentityCredential() on sign-out. Never embed the project signing secret or signing logic in the iOS app. Ask for the backend integration if it is missing; do not fabricate signatures. Chat defaults to requiring verified identity; if there are no accounts, ask the owner to enable anonymous chat in AppNorth before testing chat.
6. Build the app and resolve compilation issues. Open the new entry and send a clearly labelled test support message (or a private report using the documented client.createFeedback API). Confirm it appears in AppNorth; creating a public idea alone does not complete the first-report check. Do not send private diagnostics without explicit consent.
7. Add this reference to AGENTS.md (create it if absent), and to CLAUDE.md if it exists: "AppNorth integration docs: https://www.appnorth.app/llms.txt — start at https://www.appnorth.app/docs/get-started.md#setup-prompt." Preserve all existing instructions.
8. Summarize the files changed, where the entry lives and whether the test message reached AppNorth. Do not claim success until verified.

Set up manually

Add the package

In Xcode, choose File → Add Package Dependencies… and enter:

https://github.com/victorgxn/appnorth-ios

Choose version 0.2.0 or a compatible later version and link the AppNorth product to your app target. If your project manages dependencies in Package.swift, merge these entries into its existing package and target configuration:

// Package.swift
dependencies: [
    .package(url: "https://github.com/victorgxn/appnorth-ios", from: "0.2.0")
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "AppNorth", package: "appnorth-ios")
    ])
]

Configure a client

Create and retain a client using your public App ID. Replace YOUR_PUBLIC_APP_ID before building. The sample uses the hosted server and the localhost origin allowed by onboarding; verify the origin for your own project.

import AppNorth
import SwiftUI

let configuration = try AppNorthConfiguration(
    apiURL: URL(string: "https://www.appnorth.app")!,
    appId: "YOUR_PUBLIC_APP_ID",
    origin: URL(string: "http://localhost")!
)
let client = AppNorthClient(configuration: configuration)

struct FeedbackScreen: View {
    var body: some View {
        AppNorthView(client: client)
    }
}

The configuration initializer throws for invalid configuration. Handle that error at your app’s composition root. Keep the client in your existing state or dependency container instead of recreating it each time a view renders.

Choose an entry point

Present AppNorthView(client: client) from a row, button or sheet in your app to show its community. For a dedicated support conversation, present:

AppNorthChatView(client: client)

The community view can also show a floating chat entry when chat is enabled. To place the chat in UIKit, wrap the SwiftUI view in a UIHostingController and present it using your app’s navigation.

Configure chat access and identity

Chat defaults to requiring verified identity. If your app has accounts, have its authenticated backend issue a short-lived v1 credential. Pass the backend response to the SDK:

let credential = try AppNorthIdentityCredential(
    email: response.email,
    expiresAt: response.expiresAt,
    signature: response.signature
)
client.setIdentityCredential(credential)

Here, response is your backend’s credential response, not an SDK-provided object. Keep the project signing secret and signing logic on the backend. Clear the credential with client.clearIdentityCredential() on sign-out. Do not fabricate a signature to get past verification.

If your app has no accounts, enable anonymous chat in the project’s chat settings before testing. When chat is disabled, adding a view alone does not enable it.

Verify your first report

1. Build and run the app with the new support entry.

2. Open the conversation and send a clearly labelled test support message.

3. Open the same project in AppNorth and check that the message appears in the feedback inbox.

4. Reply from the inbox and keep the app active with chat open to check the reply.

Chat refreshes while its view is visible and the app is in the foreground. A failed message can be retried from the conversation. A public idea alone does not satisfy onboarding’s first-report check; use a support message or a private report through client.createFeedback.

If the message does not arrive

• Check that the public App ID belongs to the project you are viewing in the hub.

• Check the server base URL, network access and allowed origin.

• Check that chat is enabled and the selected mode matches your identity setup.

• For verified chat, check that the credential has not expired and was issued by your backend for this project.

• Keep chat open in the foreground when checking for a reply.

Next steps

The sidebar includes upcoming guides for community views, private feedback, identity, appearance and the full Swift API. They are marked soon while their documentation is being completed. Use the overview to understand how the SDK, App Store integrations and MCP fit together.

Keep the agent index in your project’s agent instructions so later integration work starts from the published documentation.