| OLD | NEW |
| 1 # usage | 1 # usage |
| 2 | 2 |
| 3 `usage` is a wrapper around Google Analytics for command-line, web, and Flutter
apps. | 3 `usage` is a wrapper around Google Analytics for both command-line apps and web |
| 4 apps. |
| 4 | 5 |
| 5 [](https://pub.dartlang.or
g/packages/usage) | |
| 6 [](https://travis-ci.o
rg/dart-lang/usage) | 6 [](https://travis-ci.o
rg/dart-lang/usage) |
| 7 [](https
://coveralls.io/r/dart-lang/usage?branch=master) | 7 [](https
://coveralls.io/r/dart-lang/usage?branch=master) |
| 8 | 8 |
| 9 ## For web apps | 9 ## For web apps |
| 10 | 10 |
| 11 To use this library as a web app, import the `usage_html.dart` library and | 11 To use this library as a web app, import the `usage_html.dart` library and |
| 12 instantiate the `AnalyticsHtml` class. | 12 instantiate the `AnalyticsHtml` class. |
| 13 | 13 |
| 14 When you are creating a new property at [google analytics](https://www.google.co
m/analytics/) | 14 When you are creating a new property at [google analytics](https://www.google.co
m/analytics/) |
| 15 make sure to select the **mobile app** option, not the website option. | 15 make sure to select not the website option, but the **mobile app** option. |
| 16 | |
| 17 ## For Flutter apps | |
| 18 | |
| 19 Flutter applications can use the `AnalyticsIO` version of this library. They wil
l need | |
| 20 to specify the documents directory in the constructor in order to tell the libra
ry where | |
| 21 to save the analytics preferences: | |
| 22 | |
| 23 ```dart | |
| 24 import 'package:flutter/services.dart'; | |
| 25 import 'package:usage/usage_io.dart'; | |
| 26 | |
| 27 void main() { | |
| 28 final String UA = ...; | |
| 29 | |
| 30 Analytics ga = new AnalyticsIO(UA, 'ga_test', '3.0', | |
| 31 documentsDirectory: PathProvider.getApplicationDocumentsDirectory()); | |
| 32 ... | |
| 33 } | |
| 34 ``` | |
| 35 | 16 |
| 36 ## For command-line apps | 17 ## For command-line apps |
| 37 | 18 |
| 38 To use this library as a command-line app, import the `usage_io.dart` library | 19 To use this library as a command-line app, import the `usage_io.dart` library |
| 39 and instantiate the `AnalyticsIO` class. | 20 and instantiate the `AnalyticsIO` class. |
| 40 | 21 |
| 41 Note, for CLI apps, the usage library will send analytics pings asynchronously. | 22 Note, for CLI apps, the usage library will send analytics pings asynchronously. |
| 42 This is useful it that it doesn't block the app generally. It does have one | 23 This is useful it that it doesn't block the app generally. It does have one |
| 43 side-effect, in that outstanding asynchronous requests will block termination | 24 side-effect, in that outstanding asynchronous requests will block termination |
| 44 of the VM until that request finishes. So, for short-lived CLI tools, pinging | 25 of the VM until that request finishes. So, for short-lived CLI tools, pinging |
| 45 Google Analytics can cause the tool to pause for several seconds before it | 26 Google Analytics can cause the tool to pause for several seconds before it |
| 46 terminates. This is often undesired - gathering analytics information shouldn't | 27 terminates. This is often undesired - gathering analytics information shouldn't |
| 47 negatively effect the tool's UX. | 28 negatively effect the tool's UX. |
| 48 | 29 |
| 49 One solution to this is to use the `waitForLastPing({Duration timeout})` method | 30 One solution to this is to use the `waitForLastPing({Duration timeout})` method |
| 50 on the analytics object. This will wait until all outstanding analytics requests | 31 on the analytics object. This will wait until all outstanding analytics requests |
| 51 have completed, or until the specified duration has elapsed. So, CLI apps can do | 32 have completed, or until the specified duration has elapsed. So, CLI apps can do |
| 52 something like: | 33 something like: |
| 53 | 34 |
| 54 ```dart | 35 ```dart |
| 55 await analytics.waitForLastPing(timeout: new Duration(milliseconds: 200)); | 36 analytics.waitForLastPing(timeout: new Duration(milliseconds: 500)).then((_) { |
| 56 analytics.close(); | 37 exit(0); |
| 57 ``` | 38 }); |
| 58 | |
| 59 or: | |
| 60 | |
| 61 ```dart | |
| 62 await analytics.waitForLastPing(timeout: new Duration(milliseconds: 200)); | |
| 63 exit(0); | |
| 64 ``` | 39 ``` |
| 65 | 40 |
| 66 ## Using the API | 41 ## Using the API |
| 67 | 42 |
| 68 Import the package (in this example we use the `dart:io` version): | 43 Import the package (in this example we use the `dart:io` version): |
| 69 | 44 |
| 70 ```dart | 45 ```dart |
| 71 import 'package:usage/usage_io.dart'; | 46 import 'package:usage/usage_io.dart'; |
| 72 ``` | 47 ``` |
| 73 | 48 |
| 74 And call some analytics code: | 49 And call some analytics code: |
| 75 | 50 |
| 76 ```dart | 51 ```dart |
| 77 final String UA = ...; | 52 final String UA = ...; |
| 78 | 53 |
| 79 Analytics ga = new AnalyticsIO(UA, 'ga_test', '3.0'); | 54 Analytics ga = new AnalyticsIO(UA, 'ga_test', '1.0'); |
| 80 ga.optIn = true; | 55 ga.optIn = true; |
| 81 | 56 |
| 82 ga.sendScreenView('home'); | 57 ga.sendScreenView('home'); |
| 83 ga.sendException('foo exception'); | 58 ga.sendException('foo exception'); |
| 84 | 59 |
| 85 ga.sendScreenView('files'); | 60 ga.sendScreenView('files'); |
| 86 ga.sendTiming('writeTime', 100); | 61 ga.sendTiming('writeTime', 100); |
| 87 ga.sendTiming('readTime', 20); | 62 ga.sendTiming('readTime', 20); |
| 88 ``` | 63 ``` |
| 89 | 64 |
| 90 ## When do we send analytics data? | 65 ## When do we send analytics data? |
| 91 | 66 |
| 92 You can use this library in an opt-in manner or an opt-out one. It defaults to | 67 We use an opt-in method for sending analytics information. There are essentially |
| 93 opt-out - data will be sent to Google Analytics unless the user explicitly | 68 three states for when we send information: |
| 94 opts-out. The mode can be adjusted by changing the value of the | |
| 95 `Analytics.analyticsOpt` field. | |
| 96 | 69 |
| 97 *Opt-out* In opt-out mode, if the user does not explicitly opt-out of collecting | 70 *Sending screen views* If the user has not opted in, the library will only send |
| 98 analytics (`Analytics.enabled = false`), the usage library will send usage data. | 71 information about screen views. This allows tools to do things like version |
| 72 checks, but does not send any additional information. |
| 99 | 73 |
| 100 *Opt-in* In opt-in mode, no data will be sent until the user explicitly opt-in | 74 *Opt-in* If the user opts-in to analytics collection the library sends all |
| 101 to collection (`Analytics.enabled = true`). This includes screen views, events, | 75 requested analytics info. This includes screen views, events, timing |
| 102 timing information, and exceptions. | 76 information, and exceptions. |
| 77 |
| 78 *Opt-ing out* In order to not send analytics information, either do not call the |
| 79 analytics methods, or create and use the `AnalyticsMock` class. This provides |
| 80 an instance you can use in place of a real analytics object but each analytics |
| 81 method is a no-op. |
| 103 | 82 |
| 104 ## Other info | 83 ## Other info |
| 105 | 84 |
| 106 For both classes, you need to provide a Google Analytics tracking ID, the | 85 For both classes, you need to provide a Google Analytics tracking ID, the |
| 107 application name, and the application version. | 86 application name, and the application version. |
| 108 | 87 |
| 109 Your application should provide an opt-in option for the user. If they opt-in, | 88 Your application should provide an opt-in option for the user. If they opt-in, |
| 110 set the `optIn` field to `true`. This setting will persist across sessions | 89 set the `optIn` field to `true`. This setting will persist across sessions |
| 111 automatically. | 90 automatically. |
| 112 | 91 |
| 113 *Note:* This library is intended for use with the Google Analytics application / | 92 *Note:* This library is intended for use with the Google Analytics application / |
| 114 mobile app style tracking IDs (as opposed to the web site style tracking IDs). | 93 mobile app style tracking IDs (as opposed to the web site style tracking IDs). |
| 115 | 94 |
| 116 For more information, please see the Google Analytics Measurement Protocol | 95 For more information, please see the Google Analytics Measurement Protocol |
| 117 [Policy](https://developers.google.com/analytics/devguides/collection/protocol/p
olicy). | 96 [Policy](https://developers.google.com/analytics/devguides/collection/protocol/p
olicy). |
| 118 | 97 |
| 119 ## Contributing | |
| 120 | |
| 121 Tests can be run using `pub run test`. | |
| 122 | |
| 123 ## Issues and bugs | 98 ## Issues and bugs |
| 124 | 99 |
| 125 Please file reports on the | 100 Please file reports on the |
| 126 [GitHub Issue Tracker](https://github.com/dart-lang/usage/issues). | 101 [GitHub Issue Tracker](https://github.com/dart-lang/usage/issues). |
| 127 | 102 |
| 128 ## License | 103 ## License |
| 129 | 104 |
| 130 You can view our license | 105 You can view our license |
| 131 [here](https://github.com/dart-lang/usage/blob/master/LICENSE). | 106 [here](https://github.com/dart-lang/usage/blob/master/LICENSE). |
| OLD | NEW |