Skip to main content
Install and initialize the Userpilot iOS SDK, identify users, track screens and events, and configure optional settings. The Userpilot iOS SDK enables you to capture user insights and deliver personalized in-app experiences in real time. With a one-time setup, you can immediately begin leveraging Userpilot’s analytics and engagement features to understand user behavior and guide their journeys in-app.

​
Getting Started

Before you begin, ensure your iOS project meets the following requirements:
  • iOS Deployment Target: 13 or higher.
  • Xcode: Version 15 or higher.

​
Installing the Library

​
CocoaPods

  1. Add the Userpilot dependency to your Podfile. Replace <SDK_VERSION> with the latest version available from CocoaPods.
target 'YourTargetName' do
  pod 'Userpilot', '~><SDK_VERSION>'
end
  1. Run pod install in your project directory.

​
Swift Package Manager

  1. In Xcode, navigate to File -> Add Packages.
  2. Enter the package URL: https://github.com/Userpilot/ios-sdk.
  3. For Dependency Rule, select Up to Next Major Version.
  4. Click Add Package.
Once integrated, the Userpilot SDK is available throughout your application.

​
Initialize the SDK

Initialize Userpilot once in your App Delegate or Scene Delegate during app launch to ensure the SDK is ready as soon as your app starts. Replace <APP_TOKEN> with your Application Token from the Environments Page. 
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    var userpilot: Userpilot?

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        userpilot = Userpilot(config: Userpilot.Config(token: "<APP_TOKEN>")
            .logging(true) // Enable or disable logging
        )  
        return true
    }
}

​
Identify Users (Required)

Identify unique users and companies (groups of users) alongside their properties. Once identified, all subsequent tracked events and screens will be attributed to that user.
ImportantIt’s crucial to call the Userpilot identify function; without it, Userpilot won’t be able to recognize your users, and mobile content won’t be displayed to them.
Recommended Usage:
  • On user authentication (login): Immediately call identify when a user signs in to establish their identity for all future events.
  • On app launch for authenticated users: If the user has a valid authenticated session, call identify at app launch.
  • Upon property updates: Whenever user or company properties change.
userpilot.identify(
    userId: "<USER_ID>",
    properties: [
        "name": "John Doe",
        "email": "user@example.com",
        "created_at": "2019-10-17",
        "role": "Admin"
    ],
    company: [
        "id": "<COMPANY_ID>",
        "name": "Acme Labs",
        "created_at": "2019-10-17",
        "plan": "Free"
    ]
)
Properties Guidelines
  • The id key is required in company properties to identify a unique company.
  • Userpilot supports String, Numeric, and Date types.
  • Send date values in ISO8601 format.
  • If you plan to use Userpilot’s localization features, pass the user property locale_code with a value that adheres to ISO 639-1 format.
  • Userpilot’s reserved properties have pre-determined types and improve the profiles interface in the dashboard:
    • Use key email to pass the user’s email.
    • Use key name to pass the user’s or company’s name.
    • Use key created_at to pass the user’s or company’s signup date.
Notes
  • Make sure your User ID source is consistent across all platform installations (Web, Android, and iOS).
  • While properties are optional, they are essential for Userpilot’s segmentation capabilities. We encourage you to define properties with the people responsible for Userpilot integration.

​
Track Screens (Required)

Tracking screens is crucial for unlocking Userpilot’s core engagement and analytics capabilities. Screen views are used to trigger eligible in-app experiences, improve targeting, and provide context for analytics by associating subsequent events with the currently active screen.
Userpilot SDK supports automatic screen tracking for iOS applications, allowing screen views to be captured without manually sending screen events.When Auto Capture is enabled, the SDK automatically detects and tracks screens across your app lifecycle.
Userpilot(config: Userpilot.Config(token: "<APP_TOKEN>")
    .enableScreenAutoCapture()
)
NoteAuto Capture automatically tracks screen views and ignores manually sent screen events while enabled.If you are migrating from manual screen tracking, please review the migration guide here.

​
Track Events

Log any meaningful action the user performs. Events can be button clicks, form submissions, or any custom activity you want to analyze. Optionally, you can pass metadata with the event to provide specific context. 
userpilot.track("Added to Cart", properties: ["itemId": "sku_456", "price": 29.99])

​
Logout

When a user logs out, call logout to clear the current user context. This ensures subsequent events are no longer associated with the previous user. 
userpilot.logout()

​
Anonymous Users

If a user is not authenticated, call anonymous to track events without a user ID. This is useful for pre-signup flows or guest user sessions. 
userpilot.anonymous()
Anonymous users are counted towards your Monthly Active Users usage. You should take your account’s MAU limit into consideration before applying this API.

​
Experiences

Trigger a specific experience programmatically using its ID. This API allows you to manually initiate an experience within your application. 
userpilot.triggerExperience("<EXPERIENCE_ID>")
End the current active experience: 
userpilot.endExperience()

​
Configuration (Optional)

ParameterTypeDescription
loggingBoolEnable or disable logs for the SDK.

Default: false
enableScreenAutoCaptureBoolEnables automatic screen tracking.

Default: false
enableInteractionAutoCaptureBoolEnables automatic interaction capture.

Default: false
disableRequestPushNotificationsPermissionBoolDisable push notifications permission request by the SDK.

Default: false
useInAppBrowserBooleanDetermines whether to open URLs inside SFSafariViewController or use the system browser.

Default: false
navigationHandlerUserpilotNavigationDelegateHandle deep link navigation from experiences and push notifications.
analyticsDelegateUserpilotAnalyticsDelegateBroadcasts analytics events to external listeners for tracking and reporting.
experienceDelegateUserpilotExperienceDelegateNotifies about experience display and lifecycle events.
Example Usage 
let userpilot = Userpilot(
    config: Userpilot.Config(token: "<APP_TOKEN>")
        .logging(enabled: true)
        .enableScreenAutoCapture(true)
        .enableInteractionAutoCapture(true)
        .enableUseInAppBrowser(enabled: true)
        .disableRequestPushNotificationsPermission()
)
userpilot.navigationDelegate = self
userpilot.analyticsDelegate = self
userpilot.experienceDelegate = self

​
Sample App

The Sample directory in the GitHub repository contains a full example Swift app providing references for usage of the Userpilot API.