Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(146)

Side by Side Diff: packages/usage/readme.md

Issue 2990843002: Removed fixed dependencies (Closed)
Patch Set: Created 3 years, 4 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « packages/usage/pubspec.yaml ('k') | packages/usage/test/all.dart » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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 [![pub package](https://img.shields.io/pub/v/usage.svg)](https://pub.dartlang.or g/packages/usage)
6 [![Build Status](https://travis-ci.org/dart-lang/usage.svg)](https://travis-ci.o rg/dart-lang/usage) 6 [![Build Status](https://travis-ci.org/dart-lang/usage.svg)](https://travis-ci.o rg/dart-lang/usage)
7 [![Coverage Status](https://img.shields.io/coveralls/dart-lang/usage.svg)](https ://coveralls.io/r/dart-lang/usage?branch=master) 7 [![Coverage Status](https://img.shields.io/coveralls/dart-lang/usage.svg)](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).
OLDNEW
« no previous file with comments | « packages/usage/pubspec.yaml ('k') | packages/usage/test/all.dart » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698