Integrating Userback widget into your iOS application.
- Surveys —
openSurvey(surveyKey:)opens a specific survey directly. - Screen tracking —
enterScreen/leaveScreenattribute surveys to the screen the user was on. - Multi-project support —
openFormaccepts an optionalprojectKeyargument to route feedback to a specific Userback project when your app is set up with more than one. Pass your site key (Site Settings → General) — a project's own key still works too, for existing integrations.
All of the above are additive. Existing v1 openForm(mode:, directTo:) calls keep working unchanged — no code changes required to upgrade.
dependencies: [
.package(url: "https://github.com/userback/widget-ios", from: "2.0.0")
]Or in Xcode: File > Packages > Update to Latest Package Versions, then select a 2.x version if prompted.
If you're still passing a general web widget access token (P-...) as accessToken, switch to your app's Mobile Key instead — find it in the Userback app under Workspace Settings → Mobile SDK. The Mobile Key is required for screen tracking, native events, and multi-project routing.
This repository contains UserbackSDK, an iOS SDK provided as a Swift Package.
- iOS 13.0+
- Swift 5.5+
- Xcode 13+
In Xcode, go to File > Add Package Dependencies... and enter:
https://github.com/userback/widget-ios
Select a version and add UserbackSDK to your target.
dependencies: [
.package(url: "https://github.com/userback/widget-ios", from: "1.0.0")
],
targets: [
.target(
name: "YourApp",
dependencies: ["UserbackSDK"]
)
]Call start as early as possible, typically in AppDelegate or your root view controller. Use your app's Mobile Key — found in the Userback app under Workspace Settings → Mobile SDK — not a general web widget access token (P-...):
import UserbackSDK
UserbackSDK.shared.start(accessToken: "YOUR_MOBILE_KEY")With optional configuration:
UserbackSDK.shared.start(
accessToken: "YOUR_MOBILE_KEY",
userData: ["plan": "pro"],
widgetCSS: "https://example.com/widget.css"
)UserbackSDK.shared.openForm()With options:
// Open a specific mode
UserbackSDK.shared.openForm(mode: "bug")
// Open and navigate directly to a target
UserbackSDK.shared.openForm(mode: "general", directTo: "screenshot")
// Route to a specific project, if your app has more than one set up
UserbackSDK.shared.openForm(mode: "general", projectKey: "YOUR_SITE_KEY")Find your site key under Site Settings → General — open it from the gear icon next to the site in the site switcher. A project's own key still works here too, for existing integrations.
UserbackSDK.shared.openSurvey("YOUR_SURVEY_KEY")Find a survey's key in the Userback app under that survey's settings.
Call enterScreen when a screen becomes active and leaveScreen when it's dismissed, so surveys can be attributed to the correct screen. The screen name you pass must match a screen configured in the Userback app under Survey Designer → Target → Mobile Screens — that's how a survey gets targeted to appear only on specific screens:
UserbackSDK.shared.enterScreen("ProductDetailScreen")
UserbackSDK.shared.leaveScreen("ProductDetailScreen")UserbackSDK.shared.identify(userID: "user-123", userInfo: [
"name": "Jane Smith",
"email": "jane@example.com"
])UserbackSDK.shared.setEmail("jane@example.com")
UserbackSDK.shared.setName("Jane Smith")
UserbackSDK.shared.setCategories("bug,feedback")
UserbackSDK.shared.setPriority("high")
UserbackSDK.shared.setTheme("dark")
UserbackSDK.shared.setData(["plan": "pro", "version": "2.0"])UserbackSDK.shared.close()UserbackSDK.shared.stop()// Open portal, roadmap, or announcements
UserbackSDK.shared.openPortal()
UserbackSDK.shared.openRoadmap()
UserbackSDK.shared.openAnnouncement()
// Session replay
UserbackSDK.shared.startSessionReplay()
UserbackSDK.shared.stopSessionReplay()
// Custom events
UserbackSDK.shared.addCustomEvent("checkout_tapped", details: ["item": "pro_plan"])
// Add custom request headers
UserbackSDK.shared.addHeader(key: "X-App-Version", value: "2.0")
// Refresh widget data
UserbackSDK.shared.refresh()A working example app is included in Examples/UserbackSDKExample/.
To run it:
- Open
Examples/UserbackSDKExample/UserbackSDKExample.xcodeprojin Xcode - Open
UserbackSDKExample/Info.plist - Replace
YOUR_ACCESS_TOKENwith your Userback Mobile Key (Workspace Settings → Mobile SDK) - Build and run on a simulator or device
swift test