|
1 | 1 | --- |
2 | | -title: 'Flutter Source' |
3 | | -hidden: true |
4 | | ---- |
| 2 | +title: Analytics-Flutter |
| 3 | +hidden: false |
| 4 | +--- |
| 5 | + |
| 6 | +INTRO |
| 7 | + |
| 8 | +> info "" |
| 9 | +> The Analytics-Flutter library is currently in public beta and is governed by Segment's [First Access and Beta Preview Terms](https://www.twilio.com/en-us/legal/tos){:target="_blank"}. For more information, see the [Analytics-Flutter GitHub repository](https://github.com/segmentio/analytics_flutter){:target="_blank"}. |
| 10 | +
|
| 11 | +## Getting started |
| 12 | +To install Analytics-Flutter: |
| 13 | + |
| 14 | +1. Manually add this package to your `pubspec.yaml` file: |
| 15 | + |
| 16 | + ``` |
| 17 | + dependencies: |
| 18 | + flutter: |
| 19 | + sdk: flutter |
| 20 | +
|
| 21 | + # Main package |
| 22 | + analytics: |
| 23 | + git: |
| 24 | + url: https://github.com/segmentio/analytics_flutter |
| 25 | + ref: main |
| 26 | + path: packages/core |
| 27 | + ``` |
| 28 | +2. *(Optional)* Add any pluging that you need. |
| 29 | +
|
| 30 | + ``` |
| 31 | + # Plugins |
| 32 | + analytics_plugin_firebase: |
| 33 | + git: |
| 34 | + url: https://github.com/segmentio/analytics_flutter |
| 35 | + ref: main |
| 36 | + path: packages/plugins/plugin_firebase |
| 37 | + ``` |
| 38 | +
|
| 39 | +3. Import the library in your Dart code: |
| 40 | +
|
| 41 | + ``` |
| 42 | + import 'package:analytics/client.dart'; |
| 43 | + ``` |
| 44 | +
|
| 45 | +4. Add permissions to `AndroidManifest.xml`. Add the line below between the `` tags. |
| 46 | +
|
| 47 | + ``` |
| 48 | + <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> |
| 49 | + ``` |
| 50 | +
|
| 51 | +### Setting up the client |
| 52 | +The Flutter SDK package exposes a method called `createClient` which you can use to create the Segment Analytics client. This central client manages all of the tracking events. Segment recommends that you add this as a property on your main app's state class. |
| 53 | +
|
| 54 | +``` |
| 55 | +const writeKey = 'SEGMENT_API_KEY'; |
| 56 | +final analytics = createClient(Configuration(writeKey)); |
| 57 | +``` |
| 58 | +
|
| 59 | +You must pass the `writeKey`. |
| 60 | +
|
| 61 | +These are the options you can apply to configure the client: |
| 62 | +
|
| 63 | +
|
| 64 | +| Option Name | Default | Description | |
| 65 | +| ----------- | --------- | --------| |
| 66 | +| `writeKey` **(REQUIRED)** | '' | Your Segment API key. | |
| 67 | +| `debug` | false | When set to false, it will not generate any info logs. | |
| 68 | +| `collectDeviceId` | false | Set to true to automatically collect the device ID from the DRM API on Android devices. | |
| 69 | +| `flushPolicies` | count=30,time=20s | List of flush policies controlling when to send batches of events to the plugins | |
| 70 | +| `apiHost` | "api.segment.io/v1" | Used to specify the regional Segment event endpoint | |
| 71 | +| `cdnHost` | "cdn-settings.segment.com/v1" | Used to specify the regional Segment settings endpoint | |
| 72 | +| `errorHandler` | null | Custom error handler. By default logs errors to the standard flutter logger | |
| 73 | +| `trackApplicationLifecycleEvents` | false | Enable automatic tracking for [app lifecycle events](https://segment.com/docs/connections/spec/mobile/#lifecycle-events): application installed, opened, updated, backgrounded) | |
| 74 | +| `trackDeeplinks` | false | Enable automatic tracking for when the user opens the app via a deep link. *NOTE: when sending this flag, the sdk plugin_appsflyer will ignore [onAppOpenAttribution](https://github.com/AppsFlyerSDK/appsflyer-flutter-plugin/blob/master/doc/Guides.md#Unified-deep-linking) | |
| 75 | +| `autoAddSegmentDestination`| true | Set to false to skip adding the SegmentDestination plugin | |
| 76 | +| `defaultIntegrationSettings`| null | Plugin settings that will be used if the request to get the settings from Segment fails. | |
| 77 | +| `maxBatchSize`| true | 100 | Maximum number of events to send to the API at once. | |
| 78 | +| `appStateStream`| null | Set to override the stream of application foreground or background events. | |
| 79 | +| `requestFactory`| true | Set to override the factory to generate HTTP requests. Type: [RequestFactory](https://github.com/segmentio/analytics_flutter/blob/master/packages/core/lib/state.dart#L546) | |
| 80 | +
|
| 81 | +
|
| 82 | +## Tracking methods |
| 83 | +Once you’ve installed the Analytics-Flutter library, you can start collecting data through Segment’s tracking methods: |
| 84 | +* Track |
| 85 | +* Screen |
| 86 | +* Identify |
| 87 | +* Group |
| 88 | +
|
| 89 | +### Track |
| 90 | +The [Track](/docs/connections/spec/track/) method is how you record any actions your users perform, along with any properties that describe the action. |
| 91 | +
|
| 92 | +{% codeexample %} |
| 93 | +{% codeexampletab Method signature %} |
| 94 | +```dart |
| 95 | +Future track(String event: string, {Map<String, dynamic>? properties}); |
| 96 | +``` |
| 97 | +{% endcodeexampletab %} |
| 98 | +{% codeexampletab Example use %} |
| 99 | +```dart |
| 100 | +analytics.track("View Product", properties: { |
| 101 | + "productId": 123, |
| 102 | + "productName": "Striped trousers" |
| 103 | +}); |
| 104 | +``` |
| 105 | +{% endcodeexampletab %} |
| 106 | + |
| 107 | +### Screen |
| 108 | +The [Screen](/docs/connections/spec/screen/) call lets you record whenever a user sees a screen in your mobile app, along with any properties about the screen. |
| 109 | + |
| 110 | +{% codeexample %} |
| 111 | +{% codeexampletab Method signature %} |
| 112 | +```dart |
| 113 | +Future screen(String name: string, {Map<String, dynamic>? properties}); |
| 114 | +``` |
| 115 | +{% endcodeexampletab %} |
| 116 | +{% codeexampletab Example use %} |
| 117 | +```dart |
| 118 | +analytics.screen("ScreenName", properties: { |
| 119 | + "productSlug": "example-product-123", |
| 120 | +}); |
| 121 | +``` |
| 122 | +{% endcodeexampletab %} |
| 123 | + |
| 124 | +To set up automatic screen tracking, see the [instructions below](#automatic-screen-tracking). |
| 125 | + |
| 126 | + |
| 127 | +### Identify |
| 128 | +The [Identify](/docs/connections/spec/identify/) call lets you tie a user to their actions and record traits about them. This includes a unique user ID and any optional traits you know about them like their email, name, etc. The traits option can include any information you might want to tie to the user, but when using any of the [reserved user traits](/docs/connections/spec/identify/#traits), you should make sure to only use them for their intended meaning. All reserved traits are strongly typed by the ```UserTraits``` class. When using traits not listsed as a reserved user trait, these will go under the ```custom``` property. |
| 129 | + |
| 130 | +{% codeexample %} |
| 131 | +{% codeexampletab Method signature %} |
| 132 | +```dart |
| 133 | +Future identify({String? userId, UserTraits? userTraits}); |
| 134 | +``` |
| 135 | +{% endcodeexampletab %} |
| 136 | +{% codeexampletab Example use %} |
| 137 | +```dart |
| 138 | +analytics.identify(userId: "testUserId", userTraits: UserTraits( |
| 139 | + username: "MisterWhiskers", |
| 140 | + |
| 141 | + custom: { |
| 142 | + "plan": "premium" |
| 143 | + } |
| 144 | +); |
| 145 | +``` |
| 146 | +{% endcodeexampletab %} |
| 147 | + |
| 148 | +### Group |
| 149 | + |
| 150 | + |
| 151 | +* Alias |
| 152 | +* Reset |
| 153 | +* Flush |
| 154 | + |
0 commit comments