Flutter SDK quickstart

Release notes

The Log Service Flutter SDK is published on the official Dart package repository. For more information, see Aliyun Log Flutter Release.

Sample code

The Log Service Flutter SDK provides sample code for your reference. For more examples, see Aliyun Log Flutter SDK Example.

Prerequisites

• You have installed the Flutter development environment.

• The Log Service Flutter SDK supports Android 4.0 or later and iOS 10.0 or later.

  • For iOS builds, you must add the following to your Podfile:

    source 'https://github.com/CocoaPods/Specs.git'
    source 'https://github.com/aliyun-sls/Specs.git'
    # If you are using a repository in Chinese mainland, you must also add this line.
    source 'https://gitee.com/aliyun-sls/Specs.git'

Procedure

Install the SDK

1. Create a Flutter project.

2. Add the Log Service Flutter SDK module. From the root of your project, run the following command:

   flutter pub add aliyun_log_dart_sdk

   After the process is complete, the following information is automatically added to the project's pubspec.yaml file, and flutter pub get is implicitly run.

   dependencies:
    aliyun_log_dart_sdk: ^1.0.0 // For more version information, see the Flutter SDK overview.

3. Import the package in your Dart file.

   import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

Initialize the SDK

In most cases, you can use the following code for initialization. If you need to configure the LogProducerConfiguration class, for example, to specify the size of log packages to upload or enable resumable upload, see Configuration parameters for more information.

import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

AliyunLogDartSdk? _aliyunLogSdk;

void _initProducer() async {
  // Configure the Endpoint, Project name, and Logstore name. You can dynamically update these and other parameters.
    LogProducerConfiguration configuration = LogProducerConfiguration(
      endpoint: 'your endpoint', project: 'your project', logstore: 'your logstore'
    ); 
  // An Alibaba Cloud AccessKey. Using an AccessKey pair is risky as it grants full access to your resources. We strongly recommend using a RAM User for API calls.
    configuration.accessKeyId = 'your access key id';
    configuration.accessKeySecret = 'your access key secret';
    configuration.securityToken = 'your access key token'; // Required only when using a temporary AccessKey from Security Token Service (STS).
    _aliyunLogSdk = AliyunLogDartSdk();
    LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);
}

Upload logs

You can call the addLog method to upload custom business logs.

LogProducerResult code = await _aliyunLogSdk!.addLog({
 'str': 'str value',
 'int': 12,
 'double': 12.12,
 'boolean': true,
 'map': {'key': 'value', 'inntt': 3333},
 'array': ['a1', 'a2'],
 'null': null,
 'content': 'Chinese content'
});

Logs are uploaded successfully only if code == LogProducerResult.ok. Otherwise, an error code is returned. For more information, see Error codes.

Obfuscation rules

If your Flutter project has obfuscation rules enabled (these rules are enabled by default in Flutter v1.16.2 and later), you also need to add the following rules to your project's obfuscation configuration file. Otherwise, the Android project may not run correctly. iOS projects are not affected by this rule.

-keep class com.aliyun.sls.android.producer.* { *; }
-keep interface com.aliyun.sls.android.producer.* { *; }

Dynamic configuration

You can dynamically configure parameters such as Endpoint, Project, Logstore, and AccessKey.

• Dynamically configure the Endpoint, Project, and Logstore.

  await _aliyunLogSdk!.setEndpoint('new-endpoint');
  await _aliyunLogSdk!.setProject('new-project-name');
  await _aliyunLogSdk!.setLogstore('new-logstore-name');

• Dynamically configure the AccessKey.

  // The securityToken is optional. It is required only when the AccessKey is obtained through Security Token Service (STS).
  await _aliyunLogSdk!.setAccessKey('your accesskey id', 'your accesskey secret', securityToken: 'your accesskey token');

• Dynamically configure source, topic, and tag parameters.

  await _aliyunLogSdk!.setSource('flutter');
  await _aliyunLogSdk!.setTopic('flutter-test');
  await _aliyunLogSdk!.addTag('tag1', 'value1');
  await _aliyunLogSdk!.addTag('tag2', 'value2');

• Dynamically configure other parameters.

  Important

  AliyunLogDartSdk.updateConfiguration() does not support dynamically configuring resumable upload parameters.

  LogProducerConfiguration configuration = LogProducerConfiguration();
  configuration.dropDelayLog = true;
  configuration.dropUnauthorizedLog = true;
  // Other parameters of the LogProducerConfiguration class can also be set this way.
  await _aliyunLogSdk!.updateConfiguration(configuration);

Set a log callback

You can set a callback for log-sending operations, which is triggered on success or failure. Use this callback to monitor the SDK's status or update its configuration.

_aliyunLogSdk!.setLogCallback((resultCode, errorMessage, logBytes, compressedBytes) {
	// The parameters are invalid. You need to update the configuration.
	if (LogProducerResult.parametersInvalid == resultCode) {
	// For example, update the Endpoint.
	_aliyunLogSdk!.setEndpoint('your endpoint');
	// A missing or incorrect AccessKey also triggers parametersInvalid.
	_aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
}

 	// The authorization has expired. You need to update the AccessKey.
	if (LogProducerResult.sendUnauthorized == resultCode) {
		_aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
	}
});

Enable Resumable Upload

You can refer to the following code to enable resumable upload when you initialize AliyunLogDartSdk.

configuration.persistent = true; // Enable Resumable Upload.
configuration.persistentFilePath = 'flutter/demo'; // The directory to cache binlogs.
configuration.persistentForceFlush = false; // Disable force flush. We recommend keeping this disabled, as enabling it can affect performance.
configuration.persistentMaxFileCount = 10; // The maximum number of cached files. Default: 10.
configuration.persistentMaxFileSize = 1024 * 1024; // The maximum size of a single cache file, in bytes. Default: 1024 * 1024.
configuration.persistentMaxLogCount = 64 * 1024; // The maximum number of cached logs. Default: 64 * 1024.
_aliyunLogSdk = AliyunLogDartSdk();
LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);

Parameters

The parameters supported by the LogProducerConfiguration class are listed in the following table.

Error codes