usage 3.4.1

usage #

usage is a wrapper around Google Analytics for command-line, web, and Flutter apps.

pub package Build Status Coverage Status

For web apps #

To use this library as a web app, import the usage_html.dart library and instantiate the AnalyticsHtml class.

When you are creating a new property at google analytics make sure to select the mobile app option, not the website option.

For Flutter apps #

Flutter applications can use the AnalyticsIO version of this library. They will need to specify the documents directory in the constructor in order to tell the library where to save the analytics preferences:

import 'package:flutter/services.dart';
import 'package:usage/usage_io.dart';

void main() {
  final String UA = ...;

  Analytics ga = new AnalyticsIO(UA, 'ga_test', '3.0',
    documentsDirectory: PathProvider.getApplicationDocumentsDirectory());

For command-line apps #

To use this library as a command-line app, import the usage_io.dart library and instantiate the AnalyticsIO class.

Note, for CLI apps, the usage library will send analytics pings asynchronously. This is useful it that it doesn't block the app generally. It does have one side-effect, in that outstanding asynchronous requests will block termination of the VM until that request finishes. So, for short-lived CLI tools, pinging Google Analytics can cause the tool to pause for several seconds before it terminates. This is often undesired - gathering analytics information shouldn't negatively effect the tool's UX.

One solution to this is to use the waitForLastPing({Duration timeout}) method on the analytics object. This will wait until all outstanding analytics requests have completed, or until the specified duration has elapsed. So, CLI apps can do something like:

await analytics.waitForLastPing(timeout: new Duration(milliseconds: 200));


await analytics.waitForLastPing(timeout: new Duration(milliseconds: 200));

Using the API #

Import the package (in this example we use the dart:io version):

import 'package:usage/usage_io.dart';

And call some analytics code:

final String UA = ...;

Analytics ga = new AnalyticsIO(UA, 'ga_test', '3.0');
ga.analyticsOpt = AnalyticsOpt.optIn;

ga.sendException('foo exception');

ga.sendTiming('writeTime', 100);
ga.sendTiming('readTime', 20);

When do we send analytics data? #

You can use this library in an opt-in manner or an opt-out one. It defaults to opt-out - data will be sent to Google Analytics unless the user explicitly opts-out. The mode can be adjusted by changing the value of the Analytics.analyticsOpt field.

Opt-out In opt-out mode, if the user does not explicitly opt-out of collecting analytics, the usage library will send usage data.

Opt-in In opt-in mode, no data will be sent until the user explicitly opt-in to collection. This includes screen views, events, timing information, and exceptions.

Other info #

For both classes, you need to provide a Google Analytics tracking ID, the application name, and the application version.

Note: This library is intended for use with the Google Analytics application / mobile app style tracking IDs (as opposed to the web site style tracking IDs).

For more information, please see the Google Analytics Measurement Protocol Policy.

Contributing #

Tests can be run using pub run test.

Issues and bugs #

Please file reports on the GitHub Issue Tracker.

License #

You can view our license here.

Changelog #

3.4.1 #

  • increase the support SDK range to '<3.0.0'

3.4.0 #

  • bump our minimum SDK constraint to >=2.0.0-dev.30
  • change to using non-deprecated dart:convert constants

3.3.0 #

  • added a close() method to the Analytics class
  • change our minimum SDK from 1.24.0-dev to 1.24.0 stable

3.2.0 #

  • expose the Analytics.applicationName and Analytics.applicationVersion properties
  • make it easier for clients to extend the AnalyticsIO class
  • allow for custom parameters when sending a screenView

3.1.1 #

  • make Analytics.clientId available immediately

3.1.0 #

  • switch the technique we use to determine the locale to the new dart:io Platform.localeName field
  • change our minimum SDK version to 1.24.0

3.0.1 #

  • expose the Analytics.clientId field

3.0.0+1 #

  • fixed an NPE in the usage_io getPlatformLocale() method

3.0.0 #

  • removed the use of configurable imports
  • removed the Flutter specific entry-point; Flutter apps can now use the regular dart:io entrypoint (AnalyticsIO)
  • moved the uuid library from lib/src/ to lib/uuid/
  • fixed an issue with reporting the user language for the dart:io provider
  • changed to send additional lines for reported exceptions

2.2.2 #

  • adjust the Flutter usage client to Flutter API changes

2.2.1 #

  • improve the user agent string for the CLI client

2.2.0+1 #

  • bug fix to prevent frequently changing the settings file

2.2.0 #

  • added Analytics.firstRun
  • added Analytics.enabled
  • removed Analytics.optIn

2.1.0 #

  • added Analytics.getSessionValue()
  • added Analytics.onSend
  • added AnalyticsImpl.sendRaw()

2.0.0 #

  • added a usage implementation for Flutter (uses conditional directives)
  • removed lib/usage_html.dart; use the new Analytics.create() static method
  • removed lib/usage_io.dart; use the new Analytics.create() static method
  • bumped to 2.0.0 for API changes and library refactorings

1.2.0 #

  • added an optional analyticsUrl parameter to the usage constructors

1.1.0 #

  • fix two strong mode analysis issues (overriding a field declaration with a setter/getter pair)

1.0.1 #

  • make strong mode compliant
  • update some dev package dependencies

1.0.0 #

  • Rev'd to 1.0.0!
  • No other changes from the 0.0.6 release

0.0.6 #

  • Added a web example
  • Added a utility method to time async events (Analytics.startTimer())
  • Updated the readme to add information about when we send analytics info

0.0.5 #

  • Catch errors during pings to Google Analytics, for example in case of a missing internet connection
  • Track additional browser data, such as screen size and language
  • Added tests for usage running in a dart:html context
  • Changed to a custom implementation of UUID; saved ~376k in compiled JS size

0.0.4 #

  • Moved sanitizeStacktrace into the main library

0.0.3 #

0.0.2 #

  • Fixed a bug in analytics.sendTiming()

0.0.1 #

  • Initial version, created by Stagehand


// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

/// A simple web app to hand-test the usage library.
library usage_example;

import 'dart:html';

import 'package:usage/usage_html.dart';

Analytics _analytics;
String _lastUa;
int _count = 0;

void main() {
  querySelector('#foo').onClick.listen((_) => _handleFoo());
  querySelector('#bar').onClick.listen((_) => _handleBar());
  querySelector('#page').onClick.listen((_) => _changePage());

String _ua() => (querySelector('#ua') as InputElement).value.trim();

Analytics getAnalytics() {
  if (_analytics == null || _lastUa != _ua()) {
    _lastUa = _ua();
    _analytics = new AnalyticsHtml(_lastUa, 'Test app', '1.0');

  return _analytics;

void _handleFoo() {
  Analytics analytics = getAnalytics();
  analytics.sendEvent('main', 'foo');

void _handleBar() {
  Analytics analytics = getAnalytics();
  analytics.sendEvent('main', 'bar');

void _changePage() {
  Analytics analytics = getAnalytics();
  window.history.pushState(null, 'new page', '${++_count}.html');

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  usage: ^3.4.1

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:usage/usage.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

We analyzed this package on Feb 13, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.1
  • pana: 0.13.5

Health suggestions

Fix lib/usage.dart. (-5.36 points)

Analysis of lib/usage.dart reported 11 hints, including:

line 28 col 27: Unnecessary new keyword.

line 31 col 33: Unnecessary new keyword.

line 168 col 20: Unnecessary new keyword.

line 173 col 14: Unnecessary new keyword.

line 182 col 36: Unnecessary new keyword.

Fix lib/src/usage_impl.dart. (-3.93 points)

Analysis of lib/src/usage_impl.dart reported 8 hints, including:

line 32 col 22: Unnecessary new keyword.

line 47 col 15: Unnecessary new keyword.

line 71 col 36: Unnecessary new keyword.

line 82 col 7: Unnecessary new keyword.

line 161 col 12: Unnecessary new keyword.

Fix lib/src/usage_impl_io.dart. (-2.96 points)

Analysis of lib/src/usage_impl_io.dart reported 6 hints, including:

line 30 col 13: Unnecessary new keyword.

line 32 col 13: Unnecessary new keyword.

line 89 col 51: Unnecessary new keyword.

line 97 col 7: Future results in async function bodies must be awaited or marked unawaited using package:pedantic.

line 108 col 28: Unnecessary new keyword.

Fix lib/src/usage_impl_html.dart. (-1 points)

Analysis of lib/src/usage_impl_html.dart reported 2 hints:

line 19 col 27: Unnecessary new keyword.

line 20 col 13: Unnecessary new keyword.

Fix lib/uuid/uuid.dart. (-0.50 points)

Analysis of lib/uuid/uuid.dart reported 1 hint:

line 20 col 26: Unnecessary new keyword.

Maintenance suggestions

Package is getting outdated. (-57.53 points)

The package was last published 82 weeks ago.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.30 <3.0.0
path ^1.4.0 1.6.4
Dev dependencies
browser ^0.10.0
grinder ^0.8.0
test ^0.12.0