This is the official documentation for the Amplitude Analytics Flutter SDK.
Go to the pubspec.yaml
file and add Amplitude SDK as a dependency.
1dependencies:2 amplitude_flutter: ^3.13.0
Run flutter pub get
in the terminal to install the SDK.
Add platform :ios, '10.0'
to your Podfile.
To enable Bitcode, follow Flutter's documentation.
Before you can instrument, you must initialize the SDK using the API key for your Amplitude project.
1import 'package:amplitude_flutter/amplitude.dart'; 2import 'package:amplitude_flutter/identify.dart'; 3 4class YourClass { 5 Future<void> exampleForAmplitude() async { 6 // Create the instance 7 final Amplitude analytics = Amplitude.getInstance(instanceName: "project"); 8 9 // Initialize SDK10 analytics.init(widget.apiKey);11 12 // Log an event13 analytics.logEvent('MyApp startup', eventProperties: {14 'friend_num': 10,15 'is_heavy_user': true16 });17 }18}
The Amplitude Flutter SDK runs on the top of the Amplitude Android Maintenance SDK, Amplitude iOS Maintenance SDK and Amplitude JavaScript Maintenance SDK. The following are the Dart settable config options. For other default configurations:
Name | Description | Default Value |
---|---|---|
enableCoppaControl() |
Enable COPPA (Children's Online Privacy Protection Act) restrictions on IDFA, IDFV, city, IP address and location tracking. Not supported on Flutter Web. | Coppa control is disabled by default. |
disableCoppaControl() |
Disable COPPA (Children's Online Privacy Protection Act) restrictions on IDFA, IDFV, city, IP address and location tracking. Not supported on Flutter Web. | Coppa control is disabled by default. |
setMinTimeBetweenSessionsMillis() |
int . The amount of time for session timeout if disable foreground tracking. For example, Amplitude.getInstance().setMinTimeBetweenSessionsMillis(100000) . The input parameter is in milliseconds. |
5 minutes |
setEventUploadThreshold() |
int . The maximum number of events that can be stored locally before forcing an upload. For example, Amplitude.getInstance().setEventUploadThreshold(30) . |
30 |
setEventUploadPeriodMillis() |
int . The amount of time waiting to upload pending events to the server in milliseconds. For example, Amplitude.getInstance().setEventUploadPeriodMillis(30000) . |
30000 |
setServerZone() |
String . The server zone to send to, will adjust server url based on this config. For example, Amplitude.getInstance().setServerZone(EU) . |
US |
setServerUrl() |
String . The API endpoint URL that events are sent to. Automatically selected by ServerZone . For example, Amplitude.getInstance().setServerUrl(https://www.your-server-url.com) . |
https://api2.amplitude.com/ |
setUseDynamicConfig() |
bool . Find the best server url automatically based on users' geo location. For example, setUseDynamicConfig(true) . |
false |
setOptOut() |
bool . Opt the user out of tracking. For example, Amplitude.getInstance().setOptOut(true) . |
false |
trackingSessionEvents() |
bool . Whether to automatically log "[Amplitude] Session Start" and "[Amplitude] Session End" session events corresponding to the start and end of a user's session. Not supported on Flutter Web. Learn more. |
false |
useAppSetIdForDeviceId() |
Only for Android. Whether to use app ser id as device id on Android side. Check here for the required module and permission. For example, Amplitude.getInstance().useAppSetIdForDeviceId(true) |
By default, the deviceId will be UUID+"R" |
To support high-performance environments, the SDK sends events in batches. Every event logged by the logEvent
method is queued in memory. Events are flushed in batches in background. You can customize batch behavior with setEventUploadThreshold
. By default, the serverUrl will be https://api2.amplitude.com/
. This SDK doesn't support batch mode, the batch API endpoint.
1// Events queued in memory will flush when number of events exceed upload threshold2// Default value is 303Amplitude.getInstance().setEventUploadThreshold(1);4 5// Events queue will flush every certain milliseconds based on setting6// Default value is 30,000 milliseconds7Amplitude.getInstance().setEventUploadPeriodMillis(10000);
Beginning with version 3.6.0, you can configure the server zone after initializing the client for sending data to Amplitude's EU servers. The SDK sends data based on the server zone if it's set. The server zone configuration supports dynamic configuration as well.
For earlier versions, you need to configure the serverURL
property after initializing the client.
For EU data residency, the project must be set up inside Amplitude EU. You must initialize the SDK with the API key from Amplitude EU.
1// For versions starting from 3.6.02// No need to call setServerUrl for sending data to Amplitude's EU servers3Amplitude.getInstance().setServerZone("EU");4 5// For earlier versions6Amplitude.getInstance().setServerUrl("https://api.eu.amplitude.com")
Events represent how users interact with your application. For example, "button clicked" may be an action you want to track.
1Amplitude.getInstance().logEvent('BUTTON_CLICKED');
Events can also contain properties. They provide context about the event taken. For example, "hover time" may be a relevant event property to "button click"
1Amplitude.getInstance().logEvent('BUTTON_CLICKED', {"Hover Time": "100ms"});
Events are typically stored in a buffer and flushed periodically. This behavior is configurable. You can also flush events manually
1Amplitude.getInstance().uploadEvents();
User properties help you understand your users at the time they performed some action within your app such as their device details, their preferences, or language.
Amplitude-Flutter's identify
manages this feature. You need to import identify
before using it.
1import 'package:amplitude_flutter/identify.dart';
Don't track any user data that may be against your privacy terms.
set
sets the value of a user property. You can also chain together multiple identify calls.
1final Identify identify = Identify()2 ..set('gender','female')3 ..set('age',20);4Amplitude.getInstance().identify(identify);
setOnce
sets the value of a user property one time. Later calls using setOnce
are ignored.
1final Identify identify1 = Identify();2identify1.setOnce('sign_up_date', '2015-08-24');3Amplitude.getInstance().identify(identify1);4final Identify identify2 = Identify();5identify2.setOnce('sign_up_date', '2015-08-24');6Amplitude.getInstance().identify(identify2);// is ignored
add
increments a user property by some numerical value. If the user property doesn't have a value set yet, it's initialized to 0 before being incremented.
1final Identify identify = Identify().add('karma', 0.123);2Amplitude.getInstance().identify(identify);
Adds a value or values to a user property at the beginning of the list, if the value doesn't exist in the user property yet.
If the user property doesn't have a value set yet, it's initialized to an empty list before the new values are pre-inserted. If the user property has an existing value, nothing happens.
1final Identify identify = Identify()2 ..preInsert('existing_list', 'some_property')3Amplitude.getInstance().identify(identify);
Adds a value or values to a user property at the end of the list, if the value doesn't exist in the user property yet. If the user property doesn't have a value set yet, it's initialized to an empty list before the new values are inserted. If the user property has an existing value, nothing happens.
1final Identify identify = Identify()2 ..postInsert('existing_list','some_property')3Amplitude.getInstance().identify(identify);
You can use setUserProperties
as a shorthand to set multiple user properties at one time. This method is a wrapper around Identify.set
and identify
.
1Map<String, dynamic> userProps = {2 'KEY': 'VALUE',3 'OTHER_KEY': 'OTHER_VALUE'4};5Amplitude.getInstance().setUserProperties(userProperties);
You can use arrays as user properties. You can directly set arrays or use append to generate an array.
1const colors = ["rose", "gold"];2const numbers = [4, 5];3final Identify identify = Identify()4 ..set("colors", colors)5 ..append("ab-tests", "campaign_a")6 ..prepend("existing_list", numbers);7Amplitude.getInstance().identify(identify);
prepend
prepends a value or values to a user property.append
appends a value or values to a user property array.
If the user property doesn't have a value set yet, it's initialized to an empty list before the new values are added. If the user property has an existing value and it's not a list, it's converted
into a list with the new value added.1const array = ["some_string", 56];2final Identify identify = Identify()3 ..append("ab-tests", "new-user-test")4 ..prepend("some_list", array)5Amplitude.getInstance().identify(identify);
clearUserProperties
clears all the current user's user properties.
The result is irreversible! Amplitude can't sync the user's user property values from before the wipe to any future events.
1Amplitude.getInstance().clearUserProperties();
remove
removes a value or values from a user property. If the item doesn't exist in the user property, nothing happens.
1const array = ["some_string", 56];2final Identify identify = Identify()3 ..remove("ab-tests", "new-user-test")4 ..remove("some_list",array);5Amplitude.getInstance().identify(identify);
unset
unsets and removes a user property.
1final Identify identify = Identify()2 ..unset("ab-tests", "new-user-test")3 ..unset("some_list",array);4Amplitude.getInstance().identify(identify)
Amplitude supports assigning users to groups and performing queries, such as Count by Distinct, on those groups. If at least one member of the group has performed the specific event, then the count includes the group.
For example, you want to group your users based on what organization they're in by using an 'orgId'. Joe is in 'orgId' '10', and Sue is in 'orgId' '15'. Sue and Joe both perform a certain event. You can query their organizations in the Event Segmentation Chart.
When setting groups, define a groupType
and groupName
. In the previous example, 'orgId' is the groupType
and '10' and '15' are the values for groupName
. Another example of a groupType
could be 'sport' with groupName
values like 'tennis' and 'baseball'.
Setting a group also sets the groupType:groupName
as a user property, and overwrites any existing groupName
value set for that user's groupType
, and the corresponding user property value. groupType
is a string, and groupName
can be either a string or an array of strings to indicate that a user is in multiple groups.
If Joe is in 'orgId' '15', then the groupName
would be '15'.
1// set group with a single group name2Amplitude.getInstance().setGroup("orgId", "15");
If Joe is in 'sport' 'tennis' and 'soccer', then the groupName
would be '["tennis", "soccer"]'.
1// set group with multiple group names2Amplitude.getInstance().setGroup("sport", ["tennis", "soccer"]);
Event-level groups is unavailable and its availability is yet to be determined.
Amplitude can track revenue generated by a user. Revenue is tracked through distinct revenue objects, which have special fields that are used in Amplitude's Event Segmentation and Revenue LTV charts.
This allows Amplitude to automatically display data relevant to revenue in the platform.
Amplitude doesn't support currency conversion. All revenue data should be normalized to your currency of choice before being sent.
1String productId = "product001";2int quantity = 2;3double price = 20;4double amount = 35;5Amplitude.getInstance().logRevenue(productId, quantity, price);6Amplitude.getInstance().logRevenueAmount(amount);
Price can be negative, which may be useful for tracking revenue lost (such as refunds or costs).
Use the Group Identify API to set or update the properties of particular groups. Keep these considerations in mind:
The groupIdentify
method accepts a group type string parameter and group name object parameter, and an Identify object that's applied to the group.
1final Identify identify = Identify()2 ..set("gender", "female")3 ..set("age", 20);4Amplitude.getInstance().groupIdentify("groupType", "groupValue", identify);
A session is a period of time that a user has the app in the foreground. Events that are logged within the same session have the same session_id
. Sessions are handled automatically so you don't have to manually call an API like startSession()
or endSession()
.
Amplitude groups events together by session. A session represents a single period of user activity, with a start and end time. Different SDKs track sessions differently, depending on the requirements of the platform.
On Android and iOS, you can choose to automatically log start and end session events corresponding to the start and end of a user's session. This is not supported on Flutter Web.
1//Enable automatically log start and end session events2Amplitude.getInstance().trackingSessionEvents(true);3//Disable automatically log start and end session events4Amplitude.getInstance().trackingSessionEvents(false);
Flutter web doesn't supporttrackingSessionEvents()
.
If your app has its login system that you want to track users with, you can call setUserId
at any time.
1Amplitude.getInstance().setUserId("test_user_id");
By default, device IDs are randomly generated UUIDs. You can define a custom device ID by calling setDeviceId
.
1Amplitude.getInstance().setDeviceId('test_device_id');
You can retrieve the device ID that Amplitude uses with Amplitude.getInstance().getDeviceId().
This method can return null
if a deviceId
hasn't been generated yet.
Amplitude doesn't recommend defining your own device IDs unless you have your own system for tracking user devices. Make sure the deviceId
you set is unique to prevent conflicts with other devices in your Amplitude data.
COPPA (Children's Online Privacy Protection Act) restrictions on IDFA, IDFV, city, IP address and location tracking can be enabled or disabled all at once.
Remember that apps asking for information from children under 13 years of age must comply with COPPA.
1// Enable COPPA Control2Amplitude.getInstance().enableCoppaControl();3// Disable COPPA Control4Amplitude.getInstance().disableCoppaControl();
Advertiser ID (also referred to as IDFA) is a unique identifier provided by the iOS and Google Play stores. As it's unique to every person and not just their devices, it's useful for mobile attribution. Mobile attribution is the attribution of an installation of a mobile app to its original source (for example, and ad campaign or app store search).
Mobile apps need permission to ask for IDFA, and apps targeted to children can't track at all. Consider IDFV, device id, or an email login system as alternatives when IDFA isn't available.
See iOS Advertising ID or the Android Advertising ID for more information.
Users may wish to opt out of tracking entirely, which means no events and no records of their browsing history are tracked. setOptOut
provides a way to fulfill user requests for privacy.
1//Disables instrumentation2Amplitude.getInstance().setOptOut(true);3//Enables instrumentation4Amplitude.getInstance().setOptOut(false);
Flutter SDK lets users configure their apps to use dynamic configuration. This feature finds the best server URL automatically based on app users' location.
setServerUrl
API, don't use dynamic configuration.setServerZone
to set it to EU zone.1Amplitude.getInstance().setUseDynamicConfig(true);
Flutter web support delivers the same experiences on the web as on mobile. Amplitude-Flutter starts to support flutter web from v3.8.0.
These features aren't supported in Flutter web:
enableCoppaControl
disableCoppaControl
trackingSessionEvents
. While Flutter Web doesn’t support the ability to send Start Session
and End Session
events automatically, the SDK will automatically track session IDs. You can use this for common session-based analyses like the User Session and Pathfinder charts. See our help docs on tracking sessions in Amplitude to learn more.useAppSetIdForDeviceId
Append the following Amplitude-JavaScript snippet into web/index.html
in your Flutter project. The Amplitude-JavaScript version must be v8.12.0 and higher.
1<script type="text/javascript" defer> 2 (function(e,t){var n=e.amplitude||{_q:[],_iq:{}};var r=t.createElement("script") 3 ;r.type="text/javascript" 4 ;r.integrity="sha384-UcvEbHmT0LE2ZB30Y3FmY3Nfw6puAKXz/LpCFuoywywYikMOr/519Uu1yNq2nL9w" 5 ;r.crossOrigin="anonymous";r.async=true 6 ;r.src="https://cdn.amplitude.com/libs/amplitude-8.12.0-min.gz.js" 7 ;r.onload=function(){if(!e.amplitude.runQueuedFunctions){ 8 console.log("[Amplitude] Error: could not load SDK")}} 9 ;var s=t.getElementsByTagName("script")[0];s.parentNode.insertBefore(r,s)10 ;function i(e,t){e.prototype[t]=function(){11 this._q.push([t].concat(Array.prototype.slice.call(arguments,0)));return this}}12 var o=function(){this._q=[];return this}13 ;var a=["add","append","clearAll","prepend","set","setOnce","unset","preInsert","postInsert","remove"]14 ;for(var c=0;c<a.length;c++){i(o,a[c])}n.Identify=o;var u=function(){this._q=[]15 ;return this}16 ;var l=["setProductId","setQuantity","setPrice","setRevenueType","setEventProperties"]17 ;for(var p=0;p<l.length;p++){i(u,l[p])}n.Revenue=u18 ;var d=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","enableTracking","setGlobalUserProperties","identify","clearUserProperties","setGroup","logRevenueV2","regenerateDeviceId","groupIdentify","onInit","logEventWithTimestamp","logEventWithGroups","setSessionId","resetSessionId","getDeviceId","getUserId","setMinTimeBetweenSessionsMillis","setEventUploadThreshold","setUseDynamicConfig","setServerZone","setServerUrl","sendEvents","setLibrary","setTransport"]19 ;function v(e){function t(t){e[t]=function(){20 e._q.push([t].concat(Array.prototype.slice.call(arguments,0)))}}21 for(var n=0;n<d.length;n++){t(d[n])}}v(n);n.getInstance=function(e){22 e=(!e||e.length===0?"$default_instance":e).toLowerCase()23 ;if(!Object.prototype.hasOwnProperty.call(n._iq,e)){n._iq[e]={_q:[]};v(n._iq[e])24 }return n._iq[e]};e.amplitude=n})(window,document);25</script>
The following matrix lists the minimum support for Amplitude Flutter SDK version. For Gradle Version lower than v6.7.1, use Amplitude Flutter v3.10.0.
Amplitude Flutter | Gradle | Android Gradle Plugin | Kotlin Gradle Plugin |
---|---|---|---|
3.11.+ |
6.7.1 |
3.6.4 |
1.7.10 |
Learn more about the Android Gradle Plugin compatibility, Gradle compatibility, and Kotlin compatibility.
If you have issues turning on Bitcode in iOS follow Flutter's documentation
Thanks for your feedback!
July 23rd, 2024
Need help? Contact Support
Visit Amplitude.com
Have a look at the Amplitude Blog
Learn more at Amplitude Academy
© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.