--- id: a1b2c3d4-e5f6-4789-a012-3456789abcde blueprint: guides_and_survey title: 'Guides and Surveys Flutter SDK' landing: false --- {{partial:alpha-notice}} Amplitude's Guides and Surveys Flutter SDK lets you deploy [Guides and Surveys](/docs/guides-and-surveys) in your Flutter applications. ## Requirements The Guides and Surveys Flutter SDK requires: * Dart 3.3+ * Flutter 3.7+ * [Amplitude Analytics Flutter SDK](/docs/sdks/analytics/flutter) 4.4.0+ ## Installation ### Install the SDK Add the Guides and Surveys package and the Amplitude Analytics SDK to your `pubspec.yaml`: ```yaml dependencies: amplitude_flutter: ^4.4.0 amplitude_engagement_flutter: ^0.0.5 ``` Run `flutter pub get` to install the dependencies. Run `pod install` in the `ios` directory. ```bash cd ios pod install ``` ### Initialize the SDK ```dart import 'package:app_links/app_links.dart'; import 'package:amplitude_flutter/amplitude.dart'; import 'package:amplitude_flutter/configuration.dart'; import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement; // Initialize Analytics final amplitude = Amplitude(Configuration(apiKey: 'YOUR_API_KEY')); // Connect the engagement SDK to the analytics instance await engagement.installAmplitudeEngagementPlugin(amplitude); // Handle deep links for preview mode final appLinks = AppLinks(); appLinks.getInitialLink().then((uri) async { if (uri != null) { final didHandleURL = await engagement.handleURL(uri.toString()); if (didHandleURL) { return; } // Handle a non-Amplitude SDK URL } }); appLinks.uriLinkStream.listen((uri) async { final didHandleURL = await engagement.handleURL(uri.toString()); if (didHandleURL) { return; } // Handle a non-Amplitude SDK URL }); ``` `installAmplitudeEngagementPlugin` initializes the engagement SDK using the same API key and passes the native analytics instance to the engagement layer on iOS and Android. #### Configuration options Pass an `AmplitudeInitOptions` object to `installAmplitudeEngagementPlugin` to configure the SDK: ```dart await engagement.installAmplitudeEngagementPlugin(amplitude, options: AmplitudeInitOptions( serverZone: AmplitudeServerZone.eu, logLevel: AmplitudeLogLevel.debug, )); ``` | Parameter | Type | Description | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `serverZone` | `EU` or `US` | Optional. Sets the Amplitude server zone. Set this to `EU` for Amplitude projects created in the EU data center. Default: `US` | | `serverUrl` | `string` | Optional. Custom server URL for API requests. Useful for [proxy setups](/docs/guides-and-surveys/proxy). | | `cdnUrl` | `string` | Optional. Custom CDN URL for static assets. Useful for [proxy setups](/docs/guides-and-surveys/proxy). | | `mediaUrl` | `string` | Optional. Custom URL for proxying nudge images. Useful for [proxy setups](/docs/guides-and-surveys/proxy) when firewalls block images. | | `logLevel` | `LogLevel` enum | Optional. Sets the log level. Default: `LogLevel.warn` | | `locale` | `string` | Optional. Sets the locale for [localization](/docs/guides-and-surveys/sdk#localization). Not setting a language means the SDK uses the default language. | {{partial:admonition type="warning" heading="Use the same API key for Guides & Surveys and Analytics"}} To avoid analytics mismatches and ensure accurate data collection, use the same API key for both Guides & Surveys and your Analytics SDK. Both should reference the same Amplitude project. Using different API keys can cause: - The SDK to fetch guides and surveys from the wrong project. - Analytics data to appear in different projects. - Insights and survey responses are incomplete or mismatched. Make sure the API key you provide to Guides & Surveys matches the API key used to initialize your Amplitude Analytics SDK. {{/partial:admonition}} ### Boot the SDK Boot the SDK with a user ID to enable Guides and Surveys: ```dart import 'package:amplitude_flutter/amplitude.dart'; import 'package:amplitude_flutter/events/identify.dart'; import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement; // Setting the User ID in Amplitude Analytics // --and-- passing it to boot() is necessary amplitude.setUserId('test-user-1'); // boot(userId, deviceId, userProperties) await engagement.boot( userId: 'test-user-1', deviceId: 'test-device-1', // optional if userId is set userProperties: {'plan': 'premium'}, // optional ); ``` {{partial:admonition type="note" heading=""}} At this point, you're technically done installing. While optional, Amplitude recommends that you [set up URL handling for preview mode](/docs/guides-and-surveys/guides-and-surveys-flutter-sdk#simulate-guides-and-surveys-for-preview). {{/partial:admonition}} ## Add your application to project settings After installing the SDK, add your Flutter 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 **Flutter** 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 Flutter app users. ### Set a minimum SDK version (when needed) `Minimum SDK version` is available for mobile SDK versions `3.0.0` and later. Use this setting as a safety control when you identify a critical issue in an older SDK release. To configure a minimum SDK version: 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 **Flutter** from the dropdown. 6. Enter a value in **Minimum SDK version**. When you set this value, Guides and Surveys compares the configured minimum with the SDK version in each app build: - If an app build uses an older SDK version, the SDK doesn't initialize in that build. - If an app build uses the same or newer SDK version, the SDK initializes as expected. This setting lets you stop guides and surveys on known problematic SDK versions without rolling back your application release. ## Screen tracking Call `screen` to enable screen-based targeting and the Time on Screen trigger. Guides and Surveys compares the screen string (for example, `"HomeScreen"`) with the string you set in the guide or survey page targeting section. ```dart engagement.screen('HomeScreen'); ``` ## Element targeting Pin and tooltip guides require the SDK to target specific widgets on screen. The SDK automatically enables element targeting on initialization. Tag targetable widgets with `AmplitudeEngagementView` as a `SemanticsTag` to give them a stable identifier. In the example below, use `"welcome-banner"` as the element targeting string in the Guides and Surveys dashboard. ```dart import 'package:flutter/material.dart'; import 'package:amplitude_engagement_flutter/amplitude_engagement.dart' as engagement; Semantics( tagForChildren: const engagement.AmplitudeEngagementView('welcome-banner'), child: Banner( child: Text('Welcome to the app'), ), ) ``` ## Simulate Guides and Surveys for preview Previewing guides and surveys directly in your application lets you experience what your users see. Previewing makes it easier to iterate on copy, targeting rules, and trigger logic. {{partial:admonition type="warning" heading="Deep linking required for preview"}} If your app doesn't have deep linking enabled, follow [Flutter's instructions](https://docs.flutter.dev/ui/navigation/deep-linking) to add support for deep linking. **Previewing guides and surveys on a phone, tablet, or simulator requires this configuration.** {{/partial:admonition}} ### Set up preview in Xcode (iOS) #### 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` for example. * **URL Schemes**: Paste the value you copied from Amplitude, for example `amp-abc123`. ### Set up preview in Android Studio (Android) #### 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 Android Studio Add the following intent filter to the main activity in your project's `AndroidManifest.xml` file: ```xml ``` ### URL handling for preview links The [initialization code snippet](#initialize-the-sdk) already takes care of URL handling for preview links. Specifically, this code: ```dart final appLinks = AppLinks(); appLinks.getInitialLink().then((uri) async { if (uri != null) { final didHandleURL = await engagement.handleURL(uri.toString()); if (didHandleURL) { return; } // Handle a non-Amplitude SDK URL } }); appLinks.uriLinkStream.listen((uri) async { final didHandleURL = await engagement.handleURL(uri.toString()); if (didHandleURL) { return; } // Handle a non-Amplitude SDK URL }); ``` ## Other SDK methods ### Manage themes ```dart engagement.setThemeMode(AmplitudeThemeMode.dark); // Options: auto, light, dark ``` ### Register a callback ```dart engagement.addCallback('show-alert', () { // Custom logic when the guide or survey triggers this callback }); ``` ### Reset ```dart engagement.reset('GUIDE_KEY', 0); ``` ### List ```dart final guidesAndSurveys = await engagement.list(); ``` ### Show ```dart engagement.show('GUIDE_KEY'); ``` ### Forward event Use `forwardEvent` to enable the *On event tracked* trigger in Guides and Surveys. The SDK doesn't send forwarded events to Amplitude servers; it uses them only for local trigger evaluation. ```dart engagement.forwardEvent({ 'event_type': 'Button Clicked', 'event_properties': {'name': 'Submit'}, }); ``` ### Close all ```dart engagement.closeAll(); ``` ## Known limitations ### Targeting animated elements and elements inside moving containers Pins and tooltips can't target widgets that are: - Animated or inside an animated container (they move on screen). - Inside a container that moves based on user interaction. {{partial:admonition type="note" heading=""}} Scrollable views usually work. {{/partial:admonition}} {{partial:admonition type="tip" heading="Workaround"}} Use screen-based targeting or event-based triggers to show guides, perhaps with a delay to ensure any animations have completed. Don't pin directly to elements in animated containers or containers that users can move through interaction. {{/partial:admonition}} ## Changelog You can access the changelog [here](/docs/guides-and-surveys/guides-and-surveys-mobile-sdk-changelog).