Skip to main content

Full Integration for Flutter Logs

About Shipbook​

ShipBook gives you the power to remotely gather, search and analyze your user logs and exceptions in the cloud, on a per-user & session basis.

Installation​

ShipBookSDK is available as a package on pub.dev.

Run this command in the terminal to install ShipBookSDK:

flutter pub add shipbook_flutter

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get):

dependencies:
  shipbook_flutter: ^1.1.0

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

Integrating ShipBook into your code​

Now in your Dart code, you can use:

import 'package:shipbook_flutter/shipbook_flutter.dart';

To initialize, add the following:

  Shipbook.start('YOUR_APP_ID', 'YOUR_APP_KEY');

To have a log on each class you need to create a logger:

  final log = Shipbook.getLogger('MODULE_NAME');

The usage of the log:

  log.e('the log message'); // Error log
  log.w('the log message'); // Warning log
  log.i('the log message'); // Info log
  log.d('the log message'); // Debug log
  log.v('the log message'); // Verbose log

Enable Shipbook debug logging​

If your logs weren't uploaded to Shipbook, or you're experiencing some other issue with Shipbook, you can enable Shipbook debug logging to track down the problem.

  Shipbook.enableInnerLog(true);

Linking ShipBook to a user’s information​

The SDK allows the option to associate each session with specific user information.

Register user:​

The best practice is to set registerUser before ShipBook.start. It will also work after this point however, it will require an additional api request.

  Shipbook.registerUser('USER_ID', userName: 'USER_NAME',  fullName: 'FULL_NAME', email: 'USER_EMAIL', phoneNumber: 'USER_PHONE_NUMBER', additionalInfo: {'KEY_1': 'VALUE_1', 'KEY_2': 'VALUE_2'});

The only required parameter is USER_ID.

Logout​

To logout the user, add the following code to your app’s logout function.

  Shipbook.logout();

Screen​

To log the user’s screen information, add the following code

  Shipbook.screen(screenName);

The best practice is to add this code to viewWillAppear in the view controller.

Flush​

Flush all logs on the device and send them now to the server.

  Shipbook.flush();

Get the UUID​

The SDK creates it's own UUID. So to get the UUID call te following code.

  Shipbook.getUUID()

Linking to Your Backend​

To see this app's sessions and your Node.js backend's requests in one timeline, add the header from getSessionHeaders() to the requests your app sends to your backend. See Cross-App Session Linking.

Custom Appenders​

You can create custom appenders to route logs to additional destinations such as analytics services, local databases, or test harnesses. Register your custom appender before calling start().

import 'package:shipbook_flutter/shipbook_flutter.dart';

class AnalyticsAppender implements BaseAppender {
    @override
    final String name;

    AnalyticsAppender(this.name, [Json? config]);

    @override
    void update(Json? config) {}

    @override
    void push(BaseLog log) {
        if (log is Message) {
            // Send to your analytics service
        }
    }

    @override
    void flush() {}

    @override
    void dispose() {}
}

// Register before start
Shipbook.registerAppender(
  'AnalyticsAppender',
  (name, config) => AnalyticsAppender(name, config),
);

Shipbook.start('YOUR_APP_ID', 'YOUR_APP_KEY');

Once registered, your custom appender can be configured through the Shipbook console by its type name, and assigned to loggers with the desired severity level.

Additional Information​

Static Function Alternative to getLogger​

You may use a static function in place of getLogger. This is not recommended and the caveats are listed below. When a static function activates the logger, the tag will become the filename. The usage of the logs:

import 'package:shipbook_flutter/log.dart';

...

Log.e('the log message'); // Error log
Log.w('the log message'); // Warning log
Log.i('the log message'); // Info log
Log.d('the log message'); // Debug log
Log.v('the log message'); // Verbose log

As mentioned, working with this static logger isn't ideal:

  • Performance is slower, especially in cases where the log is closed
  • The log’s information is less detailed. Ideally, you should create a logger for each class.
  • The Log name can have a name collision with a local Log class.