Guides and Surveys iOS SDK | Amplitude Guides and Surveys

Amplitude's Guides and Surveys iOS SDK enables you to deploy Guides and Surveys in your iOS applications.

Requirements

The Guides and Surveys iOS SDK requires:

User devices on iOS 15 or higher
Swift 5.9+
Amplitude iOS Swift SDK: 1.0.13+

Install and initialize the SDK

Install the Guides and Surveys iOS SDK with Swift Package Manager or CocoaPods.

In Xcode, click File > Add Packages...
Enter the repository url https://github.com/amplitude/Amplitude-Engagement-Swift
Select the Amplitude-Engagement-Swift package, version 1.0.5.
Click Add Package.

Add the following line to your Podfile, then run pod install.

pod 'AmplitudeEngagementSwift', '~> 1.0.5'

pod 'AmplitudeEngagementSwift', '~> 1.0.5'

Initialize the SDK

import AmplitudeEngagementSwift
 
// Initialize the SDK
let amplitudeEngagement = AmplitudeEngagement("YOUR_API_KEY")
 
// (optional) Add the plugin to your Amplitude instance
// (needed for event-based triggers to work)
let configuration = Configuration(
  apiKey: API_KEY
)
let amplitude = Amplitude(configuration: configuration)
amplitude.add(plugin: amplitudeEngagement.getPlugin())

import AmplitudeEngagementSwift
// Initialize the SDK
let amplitudeEngagement = AmplitudeEngagement("YOUR_API_KEY")
// (optional) Add the plugin to your Amplitude instance
// (needed for event-based triggers to work)
let configuration = Configuration(
apiKey: API_KEY
)
let amplitude = Amplitude(configuration: configuration)
amplitude.add(plugin: amplitudeEngagement.getPlugin())

Configuration options

Parameter	Type	Description
`apiKey`	`string`	Required. API key of the Amplitude project you want to use.
`initOptions.serverZone`	`EU` or `US`	Optional. Sets the Amplitude server zone. Set this to EU for Amplitude projects created in EU data center. Default: `US`
`initOptions.logLevel`	`LogLevel.None` or `LogLevel.Error` or `LogLevel.Warn` or `LogLevel.Verbose` or `LogLevel.Debug`.	Optional. Sets the log level. Default: `LogLevel.Warn`
`initOptions.locale`	`string`	Optional. Sets the locale for localization. Default: `undefined`. Not setting a language means the default language is used.

Boot the SDK

// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")
 
// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
    user_id: "USER_ID",
    device_id: "DEVICE_ID",
    user_properties: ["key": "value"]
)
amplitudeEngagement.boot(options: bootOptions)

// Basic boot with user ID
amplitudeEngagement.boot("USER_ID")
// Advanced boot with options
let bootOptions = AmplitudeBootOptions(
user_id: "USER_ID",
device_id: "DEVICE_ID",
user_properties: ["key": "value"]
)
amplitudeEngagement.boot(options: bootOptions)

Enable screen tracking (optional)

// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")

// Track screen views to trigger guides based on screens
amplitudeEngagement.screen("HomeScreen")

Enable element targeting

Pin and tooltip guides require the ability for the SDK to target specific elements on screen. To enable this in your app:

// Swift UI
 
MySwiftView {
 
}
.amplitudeView("MySwiftView")
 
let myView = MyUIKitView(...)
myView.accessibilityIdentifier = "MyView"

// Swift UI
MySwiftView {
}
.amplitudeView("MySwiftView")
let myView = MyUIKitView(...)
myView.accessibilityIdentifier = "MyView"

Manage themes

Configure the visual theme mode if your app supports light and dark modes.

// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: LIGHT, DARK, SYSTEM

// Set the theme mode
amplitudeEngagement.setThemeMode(ThemeMode.DARK) // Options: LIGHT, DARK, SYSTEM

Reset

Reset a guide or survey to a specific step.

amplitudeEngagement.reset(key = "GUIDE_KEY", stepIndex = 0)

amplitudeEngagement.reset(key = "GUIDE_KEY", stepIndex = 0)

Parameter	Type	Description
`key`	`string`	Required. The guide or survey's key.
`stepIndex`	`number`	Required. The zero-based index of the step to reset to. Defaults to the initial step.

List

Retrieve a list of all live guides and surveys along with their status.

val guidesAndSurveys = amplitudeEngagement.list()

val guidesAndSurveys = amplitudeEngagement.list()

Show

Display a specific guide or survey. Ignores any targeting rules and limits except for page targeting.

amplitudeEngagement.show(key = "GUIDE_KEY")

amplitudeEngagement.show(key = "GUIDE_KEY")

Parameter	Type	Description
`key`	`string`	Required. The guide or survey's key.

Forward event

If you don't use the plugin, but want to trigger Guides using events.

amplitudeEngagement.forwardEvent([
  "event_type": "my event type",
  "event_properties": [String: String]()
])

amplitudeEngagement.forwardEvent([
  "event_type": "my event type",
  "event_properties": [String: String]()
])

Close all

Close all active guides and surveys.

amplitudeEngagement.closeAll()

amplitudeEngagement.closeAll()

Simulate Guides and Surveys for preview

To use preview mode to test a guide or survey in your app, configure a custom URL scheme.

Locate the mobile URL scheme

In Amplitude, navigate to your Project's settings.

On the General tab, locate the URL scheme (mobile) field. Copy its value, for example, amp-abc123.

Add the URL scheme in Xcode

Open your iOS project in Xcode.
In the Project navigator, select your app's target.
On the Info tab, locate the URL Types section.
Add a new URL type with the following values:
- Identifier: Provide a descriptive name, like AmplitudeURLScheme.
- URL Schemes: Paste the value you copied from Amplitude, for example amp-abc123.

Configure URL handling for preview links

// In your AppDelegate or SceneDelegate
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if amplitudeEngagement.handleUrl(url) {
        return true
    }
    // Handle other URL schemes
    return false
}

// In your AppDelegate or SceneDelegate
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if amplitudeEngagement.handleUrl(url) {
        return true
    }
    // Handle other URL schemes
    return false
}