Simple Log Service：Flutter SDK快速入門

版本說明

Log ServiceFlutter SDK版本通過Dart包官方託管網站發布。更多資訊，請參見Aliyun Log Flutter Release。

範例程式碼

Log ServiceFlutter SDK提供相應的範例程式碼，方便您參考或直接使用。更多範例程式碼，請參見Aliyun Log Flutter SDK Example。

前提條件

• 已安裝Flutter開發環境。

• Log ServiceFlutter SDK支援Android 4.0、iOS 10.0及以上版本。

  • 其中 IOS 打包需要增加：

    source 'https://github.com/CocoaPods/Specs.git'
    source 'https://github.com/aliyun-sls/Specs.git'
    # 若是中國內地倉庫，必須添加
    source 'https://gitee.com/aliyun-sls/Specs.git'

操作步驟

安裝SDK

1. 建立Flutter專案。

2. 匯入Log ServiceFlutter SDK模組。在專案根目錄下執行以下命令：

   flutter pub add aliyun_log_dart_sdk

   執行完成後，在專案的pubspec.yaml檔案中會自動增加以下資訊，並隱式執行flutter pub get。

   dependencies:
    aliyun_log_dart_sdk: ^1.0.0 // 更多版本資訊參見：Flutter SDK概述。

3. 匯入成功後，您可以在指定的Dart檔案中匯入Log Service模組，進行引用並編寫代碼。

   import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

初始化SDK

一般情境下，您可以參考以下代碼進行初始化。若您需要配置LogProducerConfiguration類，例如配置詳細的上傳日誌包大小、開啟斷點續傳功能等。詳細配置說明，請參見配置參數說明。

import 'package:aliyun_log_dart_sdk/aliyun_log_dart_sdk.dart';

AliyunLogDartSdk? _aliyunLogSdk;

void _initProducer() async {
  // 佈建服務入口Endpoint、Project名稱、Logstore名稱。您可以通過動態參數配置動態更新Endpoint、Project名稱等。
    LogProducerConfiguration configuration = LogProducerConfiguration(
      endpoint: 'your endpoint', project: 'your project', logstore: 'your logstore'
    ); 
  //阿里雲存取金鑰AccessKey。更多資訊，請參見存取金鑰。阿里雲帳號AccessKey擁有所有API的存取權限，風險很高。強烈建議您建立並使用RAM使用者進行API訪問或日常營運。
    configuration.accessKeyId = 'your access key id';
    configuration.accessKeySecret = 'your access key secret';
    configuration.securityToken = 'your access key token'; // 僅當您使用令牌服務（STS）方式擷取臨時AccessKey時需要配置。
    _aliyunLogSdk = AliyunLogDartSdk();
    LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);
}

上報日誌

可以通過addLog方法上報自訂業務日誌。

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': '中文'
});

僅當code == LogProducerResult.ok時才表示上報日誌成功。其他情況下返回錯誤碼，請參見錯誤碼說明。

混淆規則

如果您的Flutter專案開啟了混淆規則（Flutter 1.16.2及以版本預設開啟混淆規則），您還需要在您專案的混淆設定檔中加入以下規則，否則Android專案可能無法正常運行。iOS專案不受此規則影響。

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

動態化配置參數

Log ServiceFlutter SDK支援動態化配置Endpoint、Project、Logstore、AccessKey等參數。

• 動態化配置Endpoint、Project、Logstore參數。

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

• 動態化配置AccessKey參數。

  //SecurityToken為可選值，僅當AccessKey是通過令牌服務（STS）方式擷取時必須填寫。
  await _aliyunLogSdk!.setAccessKey('your accesskey id', 'your accesskey secret', securityToken: 'your accesskey token');

• 動態化配置source、topic、tag參數。

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

• 動態化配置其他參數

  重要

  AliyunLogDartSdk.updateConfiguration()不支援動態配置斷點續傳相關的參數。

  LogProducerConfiguration configuration = LogProducerConfiguration();
  configuration.dropDelayLog = true;
  configuration.dropUnauthorizedLog = true;
  // 其他LogProducerConfiguration類的參數也可通過該方式設定。
  await _aliyunLogSdk!.updateConfiguration(configuration);

設定日誌發送回調

Log ServiceFlutter SDK支援設定日誌發送回調。日誌發送成功或失敗時，都會產生對應的回調資訊。您可以通過回調資訊來確定SDK的運行情況，或者更新SDK的參數配置。

_aliyunLogSdk!.setLogCallback((resultCode, errorMessage, logBytes, compressedBytes) {
	// 參數配置錯誤，需要更新參數。
	if (LogProducerResult.parametersInvalid == resultCode) {
	// 例如更新Endpoint配置。
	_aliyunLogSdk!.setEndpoint('your endpoint');
	// 沒有配置AccessKey，或配置錯誤也會觸發parametersInvalid。
	_aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
}

 	// 授權到期，需要更新AccessKey。
	if (LogProducerResult.sendUnauthorized == resultCode) {
		_aliyunLogSdk!.setAccessKey('your access key id', 'your access key secret', securityToken: 'your token');
	}
});

開啟斷點續傳

您可以參考如下代碼，在初始化AliyunLogDartSdk時開啟斷點續傳功能。

configuration.persistent = true; // 開啟斷點續傳。
configuration.persistentFilePath = 'flutter/demo'; // binlog緩衝目錄。
configuration.persistentForceFlush = false; // 關閉強制重新整理，建議關閉，開啟後會對效能產生一定的影響。
configuration.persistentMaxFileCount = 10; // 快取檔案數量，預設為10。
configuration.persistentMaxFileSize = 1024 * 1024; // 單個快取檔案的大小，預設為1024 * 1024。
configuration.persistentMaxLogCount = 64 * 1024; // 緩衝日誌的數量，預設為64 * 1024。
_aliyunLogSdk = AliyunLogDartSdk();
LogProducerResult result = await _aliyunLogSdk!.initProducer(configuration);

配置參數說明

LogProducerConfiguration類支援的參數配置如下表所示。

錯誤碼說明