Guides and Surveys Flutter SDK

Amplitude's Guides and Surveys Flutter SDK lets you deploy 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 4.4.0+

Installation

Install the SDK

Add the Guides and Surveys package and the Amplitude Analytics SDK to your pubspec.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.

cd ios
pod install

Initialize the SDK

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:

await engagement.installAmplitudeEngagementPlugin(amplitude, options: AmplitudeInitOptions(
  serverZone: AmplitudeServerZone.eu,
  logLevel: AmplitudeLogLevel.debug,
));

Boot the SDK

Boot the SDK with a user ID to enable Guides and Surveys:

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
);

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.

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.

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.

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:

<activity android:name=".MainActivity">
    <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <!-- Add your URL scheme from Amplitude Dashboard here -->
    <!-- ex: android:scheme="amp-12345" -->
    <data android:scheme="<your-unique-scheme-id>" />
    </intent-filter>
</activity>

URL handling for preview links

The initialization code snippet already takes care of URL handling for preview links. Specifically, this code:

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

engagement.setThemeMode(AmplitudeThemeMode.dark); // Options: auto, light, dark

Register a callback

engagement.addCallback('show-alert', () {
  // Custom logic when the guide or survey triggers this callback
});

Reset

engagement.reset('GUIDE_KEY', 0);

List

final guidesAndSurveys = await engagement.list();

Show

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.

engagement.forwardEvent({
  'event_type': 'Button Clicked',
  'event_properties': {'name': 'Submit'},
});

Close all

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.

Changelog

You can access the changelog here.