Iterate for iOS

---

Iterate surveys put you directly in touch with your app users to learn how you can change for the better—from your product to your app experience.

Run surveys that are highly targeted, user-friendly, and on-brand. You’ll understand not just what your visitors are doing, but why.

Requirements

✅ iOS 12 or higher
✅ Works with iPhone or iPad
✅ Swift 4.2 or higher
👍 No 3rd party dependencies

Install

Swift Package Manager (SPM)

• Xcode -> Project -> Package Dependencies -> Click "+"
• Paste "https://github.com/iteratehq/iterate-ios" into search bar
• Specify versioning rules and select project to add library
• Press "Add Package"

Carthage

You can install Iterate using the Carthage dependency manager by installing Carthage and adding the following to your Cartfile:

github "iteratehq/iterate-ios" ~> 1.0

Then run

$ carthage update

and follow the Carthage instructions to copy the framework into your app.

CocoaPods

You can install Iterate using the CocoaPods dependency manager by installing CocoaPods and adding the following to your Podfile:

pod 'Iterate', '~> 1.0'

Then run

$ pod install

Usage

Within your app, surveys are shown in response to events. An event can be anything from viewing a screen, clicking a button, or any other user action. You use the Iterate SDK to send events to Iterate, then from your Iterate dashboard you create surveys that target those events.

Quickstart

Log in to or Sign up for an Iterate account if you haven't already.

1. Create a new survey and select "Install in your mobile app"

2. Go to the "Preview & Publish" tab and copy your SDK API key

3. Initialize the SDK in your AppDelegate class

import Iterate

class AppDelegate: UIResponder, UIApplicationDelegate {

    // ...

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Iterate.shared.configure(apiKey: YOUR_API_KEY)
        return true
    }

    // ...

}

If you're using SwiftUI, you can attach your App to an AppDelegate and initialize using the method above

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        Iterate.shared.configure(apiKey: YOUR_API_KEY)
        return true
    }
}

4. Implement events

Here's an example of an event being fired when the user views the activity feed screen

import Iterate

class ViewController: UIViewController {

  // ...

   override func viewDidAppear(_ animated: Bool) {
       Iterate.shared.sendEvent(name: "viewed-activity-feed")
   }

   // ...

}

Here's the same example using SwiftUI

struct ActivityFeed: View {
    var body: some View {
        NavigationView {
            VStack {
                // ...
            }
        }.onAppear {
            Iterate.shared.sendEvent(name: "viewed-activity-feed")
        }
    }
}

5. On the Targeting options tab of your Iterate survey, set the survey to show when that event is triggered

6. Publish your survey and you're done 🎉

Previewing your survey

You'll likely want to preview your survey before publishing it so you can test it out and confirm everything is working correctly. You can preview using code or with a custom URL scheme. Previewing using code is easier during initial development to confirm you've installed everything correctly. Previewing using the custom URL scheme makes it easier to test on actual devices and for those without access to xcode.

Using code

In the "Preview & Publish" tab select 'Learn more' and copy the code.

This makes use of the preview method which will ensure the survey is returned once the event your survey is targeting is fired.

    override func viewDidAppear(_ animated: Bool) {
       Iterate.shared.preview(surveyId: "YOUR_SURVEY_ID")
       Iterate.shared.sendEvent(name: "viewed-activity-feed")
   }

Using a custom URL scheme

First, make sure your app has a custom URL scheme set. Then add the following code when your app is opened from your app's URL scheme.

The Iterate.shared.preview(url:) method looks for the query parameter ?iterate_preview=YOUR_SURVEY_ID which enables preview mode allowing you to see the survey in response to your targeted event being fired, but before it's published for everyone.

If you're using scenes add the following code to your SceneDelegate

import Iterate

class SceneDelegate: UIResponder, UIWindowSceneDelegate {

  // ...

  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
      for context in URLContexts {
          if context.url.isIteratePreviewURL {
              Iterate.shared.preview(url: context.url.absoluteURL)
          }
      }
  }

  // ...
}

otherwise add it to your AppDelegate

import Iterate

class AppDelegate: UIResponder, UIApplicationDelegate {

    // ...

    func application(_ application: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:] ) -> Bool {
        if (URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems?.contains { $0.name == Iterate.PreviewParameter } ?? false) {
            Iterate.shared.preview(url: url.absoluteURL)
        }

        return true
    }

    // ...

}

Once that's added you can scan the QR code on the "Preview & Publish" tab of your survey which will open your app allowing you to preview the survey once the event you're targeting has fired.

Recommendations

When implementing Iterate for the first time, we encourage you to implement events for all of your core use cases which you may want to target surveys to in the future. e.g. signup, purchased, viewed X screen, tapped notification, etc. This way you can easily launch new surveys targeting these events without needing to instrument a new event each time.

Custom fonts

Custom fonts that are available in your app bundle can be used in the Iterate survey view by passing their names to the Iterate.shared.configure method, like this:

Iterate.shared.configure(apiKey: YOUR_API_KEY, surveyTextFontName: "Merriweather-Regular", buttonFontName: "WorkSans-Regular")

The font specified in the buttonFontName parameter will be used in all survey interface buttons (question responses, previous / next buttons, etc). The font specified in surveyTextFontName will be used for all other survey text (question prompts, explanatory copy, etc).

True Type fonts and Open Type Fonts are supported. To find the correct font name to use, see Apple's documentation on custom fonts.

Associating data with a user

Using the Identify method, you can easily add properties to a user that can be used to target surveys to them and associate the information with all of their future responses.

For more information see our help article.

Note: if your app allows users to log out, you can call Iterate.shared.reset() method to clear all stored user data on logout.

Survey eligibility and frequency

By default surveys are only shown once per person and user's can only see at most 1 survey every 72 hours (which is configurable). You can learn more about how eligibility and frequency works.

Troubleshooting

If you have any issues you can head over to our help center to search for an answer or chat with our support team.