Guides and Surveys iOS SDK

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+

You can use Guides and Surveys independently of Amplitude Analytics.

Install and initialize the SDK

Guides and Surveys supports different installation options to work best with your existing Amplitude implementation, if you have one.

Using Amplitude Analytics iOS SDK

If your app uses the Amplitude Analytics iOS Swift SDK, make sure you are using version 1.13.0 or later. Then install the Guides and Surveys iOS SDK with Swift Package Manager or CocoaPods.

pod 'AmplitudeEngagementSwift', '~> 2.0.0'

Initialize the SDK

Next, make sure to initialize the SDK.

import AmplitudeEngagementSwift

let API_KEY = "YOUR_API_KEY"
let amplitudeEngagement = AmplitudeEngagement(API_KEY)

let configuration = Configuration(
  apiKey: API_KEY
)
let amplitude = Amplitude(configuration: configuration)
amplitude.add(plugin: amplitudeEngagement.getPlugin())

Configuration options

Not using Amplitude Analytics Swift SDK 1.13.0+

In this case, installation is very similar to above; however, you need to manually call .boot.

First, install the Guides and Surveys iOS SDK with Swift Package Manager or CocoaPods.

pod 'AmplitudeEngagementSwift', '~> 1.6.0'

Initialize the SDK

import AmplitudeEngagementSwift

let API_KEY = "YOUR_API_KEY"
let amplitudeEngagement = AmplitudeEngagement(API_KEY)

Configuration options

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"]
  integrations: [
    { event, eventProperties in
      // Custom event handler
    }
  ]
)
amplitudeEngagement.boot(options: bootOptions)

Add your application to project settings

After installing the SDK, add your iOS application to your Amplitude project settings so it appears as a platform option when you create guides and surveys.

To add your application:

1. Navigate to Settings > Projects in Amplitude.
2. Select your project.
3. Navigate to the Guides and Surveys tab.
4. In the App Management section, expand and click + Add App.
5. Select iOS from the dropdown.

After you add your application, it appears as a platform option when you create or edit guides and surveys. This enables you to deliver guides and surveys to your iOS app users.

Screen tracking and element targeting

Screen tracking and element targeting are technically optional, but can be very helpful for making your guides and surveys feel more targeted.

Enable screen tracking

Required for screen-based targeting and the Time on Screen trigger. The screen string (for example, "HomeScreen") is compared with the string provided in the guide or survey page targeting section.

// 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, give the element a unique identifier.

// Swift UI
MySwiftView {
  // Content
}
.amplitudeView("MySwiftView", onTrigger: {
  // Optional code to run with tap element action
})

// UIKit
let myView = MyUIKitView(...)
myView.accessibilityIdentifier = "MyView"

Other SDK methods

Manage themes

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

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

Register a callback

Set the Run callback action on a guide or survey button to execute the callback.

engagement.addCallback(_ key: String, _ function: () -> Void)

engagement.addCallback("show-alert") {
  DispatchQueue.main.async {
    let alert = UIAlertController(
      title: "Callback",
      message: "Callback has been executed!",
      preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "OK", style: .default))
    
    viewController.present(alert, animated: true)
  }
}

Router configuration

Configure how Guides and Surveys handles screen navigation.

engagement.setRouter { identifier in
  // Your screen handling and navigation
}

Reset

Reset a guide or survey to a specific step.

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

List

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

val guidesAndSurveys = amplitudeEngagement.list()

Show

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

amplitudeEngagement.show(key = "GUIDE_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]()
])

Close all

Close all active guides and surveys.

amplitudeEngagement.closeAll()

Simulate Guides and Surveys for preview

Previewing guides and surveys direclty in your application allows you to experience what your users will. Previewing makes it much easier to iterate on copy, targeting rules, trigger logic, etc.

Locate the mobile URL scheme

To locate the URL scheme:

1. Navigate to Settings > Projects in Amplitude.
2. Select your project.
3. Navigate to the General tab.
4. Find the URL scheme (mobile) field.
5. Copy its value, for example, amp-abcdefgh12345678.

Add the URL scheme in Xcode

1. Open your iOS project in Xcode.
2. In the Project navigator, select your app's target.
3. On the Info tab, locate or add the URL Types section.
4. Add a new URL type with the following values:
   • URL 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
}

Known limitations

Tab bar element targeting

Pins and tooltips can't target tab bar items (for example, UITabBar elements). Tab bars use system-level components that exist outside the standard view hierarchy, which prevents the SDK from reliably locating and attaching guides to these elements.

Targeting animated elements and elements inside moving containers

Pins and tooltips can't target views or elements that are:

• Animated or in an animated container (they move around the screen).
• In a container that can move based on user interaction.

Changelog

You can access the changelog here.