コンテンツにスキップ

SDK の初期化

このページでは、HarmonyOS SDK の初期化と実行時の機能について説明します。

基本設定

EntryAbility.ets で SDK を初期化します:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { FTSDK, FTSDKConfig, EnvType, SDKLogLevel, SyncPageSize} from '@guancecloud/ft_sdk/Index';

const DOMAIN = 0x0000;

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    this.initFTSDK();
  }

  private initFTSDK(): void {
    try {
      // ローカル環境デプロイ(Datakit)
      // const sdkConfig = FTSDKConfig.builder(datakitUrl);

      // パブリック DataWay
      const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
        .setDebug(true)
        .setSdkLogLevel(SDKLogLevel.D)
        .setServiceName('Your-App-Name')
        .setEnv(EnvType.PROD) // または文字列を使用:.setEnv('prod')
        .addGlobalContext('app_channel', new String('appgallery'))
        .setAutoSync(true)
        .setSyncPageSize(SyncPageSize.MEDIUM)
        .setDataSyncRetryCount(5)
        .setSyncSleepTime(0)
        .setCompressIntakeRequests(true);

      FTSDK.install(sdkConfig, this.context);
      hilog.info(DOMAIN, 'FTSDK', 'FT SDK initialized successfully');
    } catch (error) {
      const errorObj: object = error as object;
      hilog.error(DOMAIN, 'FTSDK', `Failed to initialize FT SDK: ${JSON.stringify(errorObj)}`);
    }
  }
}
メソッド名 型 必須 説明
datakitUrl string アップロード前に設定が必要、または DataWay を選択 ローカル環境デプロイ(DataKit)のレポート URL アドレス(例:http://10.0.0.1:9529)。デバイスからこのアドレスにアクセスできる必要があります。実行時に追加できます。詳細は動的更新アドレスを参照してください
datawayUrl string アップロード前に設定が必要、または DataKit を選択 パブリック DataWay のレポート URL アドレス。RUM アプリから取得します(例:https://open.dataway.url)。実行時に追加でき、datakitUrl とはいずれか一方を選択します
clientToken string DataWay モードでは必須 認証 Token。datawayUrl と同時に設定する必要があります
setDebug boolean いいえ SDK 内部の診断ログを有効にするかどうか。デフォルトは false
setSdkLogLevel SDKLogLevel いいえ SDK 内部ログの出力レベルを設定します。詳細はトラブルシューティングを参照してください
setEnableInnerLogFile enable: boolean, config?: FTInnerLogFileConfig いいえ SDK 内部ログをローカルファイルに書き込むかどうか。デフォルトは false。詳細はトラブルシューティングを参照してください
setEnv string \| EnvType いいえ 環境。デフォルトは prod。EnvType 列挙型または文字列を指定できます
setServiceName string いいえ 所属するビジネスまたはサービスの名前。デフォルトは df_rum_harmonyos
addGlobalContext key: string, value: object いいえ SDK のグローバルプロパティを追加します。追加ルールはこちらを参照してください
setAutoSync boolean いいえ データ収集後に自動でサーバーへ同期するかどうか。デフォルトは true。false に設定した場合は、FTSDK.flushSyncData() を使用してデータ同期を独自に管理できます
setSyncPageSize SyncPageSize いいえ 事前定義された同期リクエストの件数を設定します。MINI は 5 件、MEDIUM は 10 件、LARGE は 50 件、デフォルトは SyncPageSize.MEDIUM
setCustomSyncPageSize number いいえ 同期リクエストの件数をカスタム設定します。範囲は [5, 500]、小数は切り捨て、デフォルトは 10。setSyncPageSize とはいずれか一方を設定します
setDataSyncRetryCount number いいえ 1 回のデータ同期における最大リトライ回数を設定します。範囲は [0, 5]、小数は切り捨て、デフォルトは 5
setSyncSleepTime number いいえ 連続する同期リクエスト間の間隔時間を設定します。範囲は [0, 5000]、単位はミリ秒、デフォルトは 0
setCompressIntakeRequests boolean いいえ アップロードデータに zlib でラップした deflate 圧縮を使用するかどうか。デフォルトは true。圧縮が使用できない場合は平文アップロードにフォールバックします
setProxy FTProxyConfig \| null いいえ SDK のデータアップロードリクエストで使用する HTTP プロキシを設定します。null を渡すとプロキシ設定をクリアできます
setProxyAuthenticator FTProxyAuthenticator \| null いいえ アップロードプロキシの認証情報を設定します。null を渡すと独立した認証設定をクリアできます
setDns FTDnsConfig \| null いいえ SDK のデータアップロードリクエストで使用する DNS サーバーまたは DNS over HTTPS アドレスを設定します。null を渡すと DNS 設定をクリアできます
setDataModifier DataModifier \| null いいえ 単一のフィールドを変更またはマスキングします。null を返すと元の値を保持します。詳細はデータ収集のマスキングを参照してください
setLineDataModifier LineDataModifier \| null いいえ 1 件のデータに存在するフィールドを一括で変更またはマスキングします。詳細はデータ収集のマスキングを参照してください
setEnableDataFilter boolean いいえ DataKit 互換のローカルおよびリモートのブロックリストフィルタリング機能を有効にするかどうか。デフォルトは true。Logging と RUM データのフィルタリングをサポートします。詳細はブロックリストフィルタリングを参照してください
setDataFilters FTDataFilters \| null いいえ ローカルのブロックリストフィルタリングルールを設定します。logging、rum の 2 種類のルールをサポートします。null を渡すとローカルルールをクリアできます。詳細はブロックリストフィルタリングを参照してください
setAllowWebViewHost Array<string> \| null いいえ WebView RUM と Replay が Bridge を使用する Host の範囲を一括設定します。null はすべての Host を許可し、空配列は Bridge による収集を無効化し、非空配列は指定した Host およびそのサブドメインに一致します。この設定は Bridge の選択に使用され、ページオリジンのセキュリティ検証機構としては機能しません
setEnableAccessDeviceID boolean いいえ システムのデバイス識別子を device_uuid として使用するかどうか。デフォルトは false。無効時は SDK が永続化するプライバシー UUID を使用します。実行時の切り替え方法はデバイス識別子の動的な有効化と無効化を参照してください
setOnlySupportMainProcess boolean いいえ メインプロセスでのみ初期化するかどうか。デフォルトは true。サブプロセスを監視する必要がある場合は、インストール前に false に設定します
setRemoteConfiguration boolean いいえ データ収集のリモート設定機能を有効にするかどうか。デフォルトは false。有効にすると、SDK は RUM 設定のインストールが完了し、有効なレポートアドレスが存在する場合に設定を取得します
setRemoteConfigMiniUpdateInterval number いいえ データ更新の最短間隔を設定します。単位は秒、デフォルトは 12 時間
setRemoteConfigurationCallBack FTRemoteConfigFetchResult \| null いいえ リモート設定結果のコールバック。詳細はコード例を参照してください
setNeedTransformOldCache boolean いいえ 旧キャッシュデータを移行するかどうか。デフォルトは false。初めて FileStore に切り替え、既存の SQLite キャッシュを保持する必要がある場合に有効にします。ft-sdk 0.1.17 以降のバージョンでサポートされます。
enableFileDataStore Void いいえ ファイルキャッシュを有効にします。同期キャッシュと RUM 集約データに使用します。デフォルトでは引き続き SQLite キャッシュを使用します。ft-sdk 0.1.17 以降のバージョンでサポートされます。
setUseFileDataStore boolean いいえ ファイルキャッシュを使用するかどうかを設定します。true を渡すと FileStore を使用し、false を渡すとデフォルトの SQLite キャッシュを使用します。ft-sdk 0.1.17 以降のバージョンでサポートされます。
setFileDataStoreShadow boolean いいえ ファイルキャッシュのシャドウ書き込みを有効にします。有効にすると、読み取りとアップロードは引き続き SQLite を使用し、同時に書き込みを FileStore にミラーリングします。移行前の検証に使用します。ft-sdk 0.1.17 以降のバージョンでサポートされます。
enableLimitWithCacheSize cacheSize?: number いいえ 総キャッシュサイズの制限を有効にします。デフォルトは 100MB、単位は Byte。渡す値の最小は 30MB。有効にすると Log と RUM の件数制限は無効になります。ft-sdk 0.1.17 以降のバージョンでサポートされます。
setCacheDiscard CacheDiscard いいえ キャッシュがサイズ上限に達した後の破棄ポリシーを設定します。デフォルトは CacheDiscard.DISCARD。DISCARD は新規データを破棄し、DISCARD_OLDEST は最も古いキャッシュデータを削除します。ft-sdk 0.1.17 以降のバージョンでサポートされます。
enableLimitWithDbSize cacheSize?: number いいえ 非推奨。旧バージョンとの互換性のために残されています。enableLimitWithCacheSize の使用を推奨します。
setDbCacheDiscard DBCacheDiscard いいえ 非推奨。旧バージョンとの互換性のために残されています。setCacheDiscard の使用を推奨します。

動的設定と実行時のレポートアドレス更新の使用方法については、動的設定と動的更新アドレスを参照してください。

ファイルキャッシュ

ft-sdk 0.1.17 以降のバージョンでは、同期キャッシュと RUM 集約データをファイルキャッシュに書き込むことができます。スムーズなアップグレードのため、SDK はデフォルトで引き続き SQLite キャッシュを使用します。ファイルキャッシュを有効にする場合は、FTSDKConfig で明示的に有効化できます。

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .enableFileDataStore();

ファイルキャッシュの書き込み状況を先に検証する場合は、シャドウ書き込みを有効にできます。有効にすると、SDK は引き続き SQLite からデータを読み取ってアップロードし、同時に書き込みを FileStore にミラーリングします。検証が完了したら enableFileDataStore() に切り替えます。

const shadowConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setFileDataStoreShadow(true);

キャッシュサイズ制限

ft-sdk 0.1.17 以降のバージョンでは、enableLimitWithCacheSize を使用して SDK の総キャッシュサイズ制限を設定することを推奨します。有効にすると、個別のログ件数上限 FTLoggerConfig.setLogCacheLimitCount と RUM 件数上限 FTRUMConfig.setRumCacheLimitCount は無効になります。

import { CacheDiscard, FTSDKConfig } from '@guancecloud/ft_sdk/Index';

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  // 総キャッシュサイズ制限を有効にします(例:100MB)。
  .enableLimitWithCacheSize(100 * 1024 * 1024)
  // キャッシュが上限に達したら最も古いキャッシュデータを削除します。
  .setCacheDiscard(CacheDiscard.DISCARD_OLDEST);

アップロードのネットワーク設定

setProxy(...)、setProxyAuthenticator(...)、setDns(...) は、SDK が DataKit または DataWay にデータをアップロードするリクエストにのみ作用し、アプリのビジネスリクエストのネットワーク設定は変更しません。

import {
  FTSDK,
  FTSDKConfig,
  FTProxyConfig,
  FTProxyAuthenticator,
  FTDnsConfig
} from '@guancecloud/ft_sdk/Index';

const proxyConfig: FTProxyConfig = {
  host: 'proxy.example.com',
  port: 8080,
  exclusionList: ['localhost', '127.0.0.1']
};

const proxyAuthenticator: FTProxyAuthenticator = {
  username: 'proxy-user',
  password: 'proxy-password'
};

const dnsConfig: FTDnsConfig = {
  servers: ['1.1.1.1', '8.8.8.8'],
  overHttpsUrl: 'https://dns.example.com/dns-query'
};

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setProxy(proxyConfig)
  .setProxyAuthenticator(proxyAuthenticator)
  .setDns(dnsConfig);

FTSDK.install(sdkConfig, this.context);

FTProxyConfig

フィールド 型 必須 説明
host string はい プロキシサーバーのアドレス
port number はい プロキシサーバーのポート
exclusionList Array<string> いいえ プロキシを使用しないホストのリスト。NetworkKit のプロキシ除外ルールに従います
username string いいえ プロキシユーザー名。setProxyAuthenticator(...) で個別に設定することもできます
password string いいえ プロキシパスワード。setProxyAuthenticator(...) で個別に設定することもできます

FTProxyAuthenticator

フィールド 型 必須 説明
username string はい プロキシ認証のユーザー名
password string はい プロキシ認証のパスワード

FTProxyConfig と FTProxyAuthenticator の両方に認証情報を設定した場合、FTProxyAuthenticator の設定が優先されます。

FTDnsConfig

フィールド 型 必須 説明
servers Array<string> いいえ カスタム DNS サーバーのアドレス。空文字列は無視され、有効な先頭 3 件のアドレスまで使用されます
overHttpsUrl string いいえ DNS over HTTPS サービスのアドレス

ブロックリストフィルタリング

ft-sdk 0.1.15 は DataKit 互換のブロックリストフィルタリングをサポートしており、データをローカルキャッシュに書き込む前に Logging、RUM データをフィルタリングするために使用します。この機能はデフォルトで有効であり、setEnableDataFilter(false) で無効にできます。

ブロックリストルールはローカルルールとリモートルールに分かれます:

  • ローカルルールは setDataFilters で設定し、logging、rum の 2 種類のルールをサポートします。
  • データフィルタリングが有効で、有効なレポートアドレスが存在する場合、SDK は DataKit または DataWay からリモートの logging、rum ルールを取得します。
  • ローカルルールとリモートルールは同時に新規データをフィルタリングします。ルールに一致したデータはローカルキャッシュに書き込まれません。
  • データはまず LineDataModifier で変更され、変更後の内容に基づいてブロックリストフィルタリングが行われます。
  • リモートルールはアップロード前に一致したキャッシュデータをクリアします。ローカルルールは新規データのみをフィルタリングします。
  • SDK はアップロードタスクを開始するたびにリモートルールの有効期限を確認し、期限切れの場合にのみ取得します。
  • サーバー側の pull_interval が数値の場合、単位はナノ秒です(例:10000000000 は 10 秒)。文字列の数値 "10" は 10 秒を表し、"10s"、"2m"、"1h" など単位付きの形式もサポートします。欠落または無効な場合は 10 秒として処理されます。
  • サーバー側の返却内容が変化していない場合、SDK は同じルールを繰り返し解析または適用しません。

ルール式は {} 内に記述する必要があり、in、not in、match、not match 演算子をサポートし、複数の条件は and / or で組み合わせられます。フィールドのソースにはデータタグとフィールドが含まれ、source、measurement、class などのデータ型識別フィールドもサポートします。match は正規表現を使用します。

import {
  FTSDK,
  FTSDKConfig,
  FTDataFilters
} from '@guancecloud/ft_sdk/Index';

const dataFilters: FTDataFilters = new Map<string, Array<string>>();
dataFilters.set('logging', [
  "{ source in ['df_rum_harmonyos_log'] and message match ['.*password.*'] }"
]);
dataFilters.set('rum', [
  "{ source in [resource] and resource_status in ['404', '503'] }"
]);

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setEnableDataFilter(true)
  .setDataFilters(dataFilters);

FTSDK.install(sdkConfig, this.context);

FTDataFilters には Map<string, Array<string>> または同じ構造のオブジェクトを渡せます。カテゴリ名は大文字と小文字を区別しません。logging、rum 以外のカテゴリは無視されます。

// ローカルおよびリモートのブロックリストフィルタリングを無効にしますが、設定済みのローカルルールは保持します。
sdkConfig.setEnableDataFilter(false);

// 設定済みのローカルルールをクリアします。サーバー側のリモートルールには影響しません。
sdkConfig.setDataFilters(null);

実行時に有効なレポートアドレスに切り替えると、SDK は旧アドレスのリモートルールをクリアし、新アドレスから再度取得します。ローカルルールは引き続き保持されます。

ユーザーのバインドとアンバインド

使用方法

/**
 * ユーザー情報をバインドします(ユーザー ID のみ)
 * @param id ユーザー ID
 */
static bindRumUserDataById(id: string): void

/**
 * ユーザー情報をバインドします(完全なユーザーデータ)
 * @param userData ユーザーデータオブジェクト
 */
static bindRumUserData(userData: UserData): void

/**
 * ユーザー情報をアンバインドします
 */
static unbindRumUserData(): void

UserData

メソッド名 説明 必須 注意
setId ユーザー ID を設定します いいえ
setName ユーザー名を設定します いいえ
setEmail メールアドレスを設定します いいえ
setExts ユーザー拡張を設定します いいえ 追加ルールはカスタムタグとグローバルコンテキストを参照してください

コード例

import { FTSDK, UserData } from '@guancecloud/ft_sdk/Index';

// 方法 1:ユーザー ID のみをバインドします(クイックバインドに推奨)
FTSDK.bindRumUserDataById('user_001');

const userData = new UserData();
userData.setId('user_001');
userData.setName('test.user');
userData.setEmail('test@mail.com');
userData.setExts({
  'user_type': 'vip'
});
FTSDK.bindRumUserData(userData);

FTSDK.unbindRumUserData();

実行時の機能

自動同期データの設定

SDK の初期化後、FTSDK.setAutoSync(...) でキャッシュデータの自動同期を動的に有効または無効にできます。無効にした場合、SDK は収集したデータを引き続きローカルキャッシュに書き込みますが、収集後に自動でアップロードをトリガーしません。FTSDK.flushSyncData() と組み合わせてデータ同期を独自に管理できます。

import { FTSDK } from '@guancecloud/ft_sdk/Index';

// 自動同期を無効にします
FTSDK.setAutoSync(false);

// 自動同期を有効にします
FTSDK.setAutoSync(true);

FTSDKConfig.setAutoSync(...) は SDK 初期化時の同期状態を設定するために使用します。FTSDK.setAutoSync(...) は SDK 初期化後に同期状態を動的に変更するために使用します。

データの明示的な同期

自動同期が無効な場合、データ同期を明示的にトリガーできます:

import { FTSDK } from '@guancecloud/ft_sdk/Index';

FTSDK.flushSyncData();

自動同期が有効な場合、SDK は 10 秒の集約ウィンドウを使用し、短時間に連続して発生したデータをマージしてアップロードします。flushSyncData() はこの集約ウィンドウを待機しません。まず現在処理待ちの RUM および Log worker キューを可能な限りローカル同期キャッシュにフラッシュし、その後すぐにアップロードタスクをスケジュールします。キューのフラッシュに失敗した場合でも、アップロードのトリガーを試みます。

SDK キャッシュデータのクリア

import { FTSDK } from '@guancecloud/ft_sdk/Index';

await FTSDK.clearAllData();

clearAllData() は未報告のすべてのキャッシュデータを削除します。これには以下が含まれます:

  • 同期データテーブル(sync_data_flat)のすべてのデータ
  • RUM ビューデータテーブル(rum_view)のすべてのデータ
  • RUM アクションデータテーブル(rum_action)のすべてのデータ

フィードバック

このページは役に立ちましたか?