usage 3.4.1

  • readme.md
  • changelog.md
  • Example
  • Installing
  • Versions
  • 97

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));
analytics.close();

or:

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

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.sendScreenView('home');
ga.sendException('foo exception');

ga.sendScreenView('files');
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

example/example.dart

// 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');
    _analytics.sendScreenView(window.location.pathname);
  }

  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');
  analytics.sendScreenView(window.location.pathname);
}

Use this package as a library

1. Depend on it

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


dependencies:
  usage: ^3.4.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages 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';
  
Version Uploaded Documentation Archive
3.4.1 Jul 17, 2018 Go to the documentation of usage 3.4.1 Download usage 3.4.1 archive
3.4.0 Apr 10, 2018 Go to the documentation of usage 3.4.0 Download usage 3.4.0 archive
3.3.0 Jul 1, 2017 Go to the documentation of usage 3.3.0 Download usage 3.3.0 archive
3.2.0+1 Jun 23, 2017 Go to the documentation of usage 3.2.0+1 Download usage 3.2.0+1 archive
3.2.0 Jun 23, 2017 Go to the documentation of usage 3.2.0 Download usage 3.2.0 archive
3.1.1 Jun 20, 2017 Go to the documentation of usage 3.1.1 Download usage 3.1.1 archive
3.1.0 Apr 24, 2017 Go to the documentation of usage 3.1.0 Download usage 3.1.0 archive
3.0.1 Mar 27, 2017 Go to the documentation of usage 3.0.1 Download usage 3.0.1 archive
3.0.0+1 Feb 14, 2017 Go to the documentation of usage 3.0.0+1 Download usage 3.0.0+1 archive
3.0.0 Feb 6, 2017 Go to the documentation of usage 3.0.0 Download usage 3.0.0 archive

All 28 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
93
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
97
Learn more about scoring.

We analyzed this package on Nov 14, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0
  • pana: 0.12.6

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:usage/usage.dart.

Health suggestions

Format lib/uuid/uuid.dart.

Run dartfmt to format lib/uuid/uuid.dart.

Dependencies

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