SDKのカスタマイズ

SDKのカスタマイズ

お知らせ:当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

概要

SDK カスタマイズとは、ソフトウェア開発キット(SDK)をアプリケーションや開発環境の特有の要件に合わせて調整することを指します。通常、SDK には、ツール、ライブラリ、ドキュメント、そしてコードサンプルが含まれており、開発者がアプリケーションを構築する際に役立ちます。

PageSense SDK を初期設定で初期化すると、以下の構成で PageSenseClient インスタンスが作成されます。
  1. ポーリング間隔:10 秒(10,000 ミリ秒)に設定されています。つまり、SDK は 10 秒ごとに PageSense サーバーにアクセスし、プロジェクト設定の更新があるか確認します。
  2. ログレベル:INFO に設定されています。これにより、SEVERE、エラー、注意、INFO レベルのすべてのログメッセージが記録されます。
  3. ロガー:SDK は組み込みのロガーを使用し、すべてのログをアプリケーションのコンソールに出力します。ログの取得を開始するための追加設定は不要です。
これらのデフォルト設定は迅速な統合に最適で、ほとんどの標準的な利用ケースに対応しています。

カスタマイズ可能な設定

柔軟性とカスタマイズ性を高めるため、PageSense SDK ではいくつかのオプション設定関数を提供しています。これらの関数を利用することで、SDK の動作のさまざまな側面を制御できます。SDK の初期化時に設定を指定することで、アプリケーションの要件や環境により適した動作とすることが可能です。

機能

説明

Polling Interval

SDK が PageSense サーバーからプロジェクト設定の更新を取得する頻度を指定します。これにより、PageSense アプリケーションで定義された最新のプロジェクト設定と同期が保たれます。

Logger

カスタムロガーを組み込むことで、SDK のログの取得先や保存方法を柔軟に制御できます。特に、エンタープライズ全体のログ管理フレームワークと統合する場合に便利です。

ユーザー Storage サービス

カスタムユーザー storage メカニズムを利用して、異なるA/Bテスト実験間でバリエーションの割り当てを永続化できます。

Log Level

記録するログメッセージの最小レベルを定義します。サポートされているレベルは、TRACEDEBUGINFOWARNエラー、およびSEVEREです。

Polling Interval

addPollingInterval関数を使用すると、PageSense SDKのポーリングサービスの間隔を設定できます。
デフォルトでは、ポーリング間隔の値は10秒に設定されています。addPollingInterval関数を呼び出すことで、ポーリング間隔を変更できます。詳細は下記をご覧ください。

例 コード

  1. PageSenseClient pageSenseClient = PageSenseClientBuilder.GetBuilder(projectSettings).AddPollingInterval(60000).BuildClient();

パラメーター詳細

パラメーター
種類
説明
addPollingInterval
整数
SDKのポーリングサービスの間隔を設定します

APIは、ポーリング間隔を設定するためにミリ秒単位の時間を受け付けます。上記の例では、ポーリング間隔が60000ミリ秒に設定されており、これは60秒と同じです。
1. ポーリング間隔は、アプリケーションの更新頻度、想定されるトラフィック量、サーバーのパフォーマンスに基づいて選択してください。
2. 短い間隔(<10秒)に設定すると、以下の事象が発生する可能性があります:
a. サーバー負荷の増加
b. ネットワークトラフィックの増加
c. 更新頻度が高い場合の競合状態の発生
3. 長い間隔(>5分)に設定すると、次のような影響が生じる可能性があります:
a. PageSenseから最新のプロジェクト設定変更が反映されるまでに遅延が発生します。
b. ユーザーに古いプロジェクト設定のA/Bテスト実験が提供される場合があります。

ログレベル

addlogLevel関数は、PageSense SDKの組み込みロガー用のログレベルを設定できます。この設定により、PageSenseClientによって出力されるログの詳細度をコントロールでき、ファイルシステムの容量に応じてログ保存を効率的に管理できます。
ログレベルを指定することで、記録されるログメッセージの最小重大度を定義します。ログレベルは文字列で指定し、以下のいずれかの値(大文字・小文字は問いません)を設定できます: TRACE、DEBUG、INFO、注意、エラー、SEVERE。

例 コード

  1. PageSenseClient pageSenseClient = PageSenseClientBuilder.GetBuilder(projectSettings).AddLogLevel(“DEBUG”).BuildClient();

パラメーター詳細

Param
種類
説明
logLevel
String
記録する最小のログ重大度を指定します

上記の例では、ログレベルがDEBUGに設定されています。そのため、DEBUG、INFO、注意、エラー、SEVEREの重大度を持つすべてのログメッセージがキャプチャされ、顧客のコンソールに書き込まれます。

カスタム logger

組み込みのSDKロガーに加え、PageSense SDKでは独自のカスタムロガーを連携してアプリケーション処理を記録できます。既存のロギングフレームワークを利用している場合や、ログの管理方法をさらに細かく制御したい場合に便利です。

addCustomLogger関数を使うことで、ユーザー定義のロガーを登録し、PageSense SDKでログ処理に利用できます。カスタムロガーを指定した場合、PageSense SDKはすべてのログメッセージを組み込みロガーの代わりにユーザー実装へルーティングします。

例 コード

  1. PageSenseClient pageSenseClient = PageSenseClientBuilder.getBuilder(projectSettings).addCustomLogger(customLogger).buildClient();

Parameter 詳細

Param
種類
説明
customLogger
PageSenseLogger のインスタンス
記録する最小のログ重大度を指定します

上記の例では、customLogger は PageSenseLogger インターフェースを実装したクラスのインスタンスです。addCustomLogger に渡す前に、必要なロギング動作を処理できるよう、このインターフェースをカスタムロガーで実装する必要があります。

例 コード

  1. using System;
  2. using log4net;
  3.  
  4. /// <概要>
  5. /// log4net ベースのロガー実装で、PageSenseLogger システムと連携します。
  6. /// log4net から最も高い有効なログレベルを自動検出し、PageSenseLogger を設定します。
  7. ///
  8. 公開する クラス Log4NetLogger : PageSenseLogger
  9. {
  10.     /// <概要>
  11. /// log4net ロガーインスタンスを使用して、実際のロギング呼び出しを委任します。
  12. /// 基本となる log4net 設定で有効なレベルに基づいてメッセージを記録します。
  13. ///
  14. 非公開 readonly ILog logger;
  15.  
  16.     /// <概要>
  17. /// 指定されたクラス名用の Log4NetLogger を作成します。
  18. ///
  19. /// <パラメーター名='className'>ロギング対象となるクラス。
  20. 公開する Log4NetLogger(string className)
  21. : base(className, DetermineMaxLogLevel(LogManager.GetLogger(className)))
  22. {
  23. this.logger = LogManager.GetLogger(className);
  24. }
  25.  
  26.     /// <概要>
  27. /// 現在有効な log4net の最大ログレベルを判定します。
  28. /// そして、その結果を PageSenseLogger で期待される形式に合った文字列として返します。
  29. ///
  30. /// <パラメーター名='logger'>log4net ロガーインスタンス。
  31. /// <返品>最も高い有効なログレベルの名前。
  32. 非公開 static string DetermineMaxLogLevel(ILog logger)
  33. {
  34. if (logger.IsDebugEnabled) 返品する 'DEBUG';
  35. if (logger.IsInfoEnabled) 返品する 'INFO';
  36. if (logger.IsWarnEnabled) 返品する '注意';
  37. if (logger.IsErrorEnabled) 返品する 'エラー';
  38. if (logger.IsFatalEnabled) 返品する 'SEVERE'; // SEVERE を FATAL にマッピング
  39.  
  40. // いずれのレベルも有効でない場合のフォールバック
  41. 返品する 'INFO'; // デフォルトのフォールバックレベル
  42. }
  43.  
  44.  
  45.     /// <概要>
  46. /// TRACEレベルのメッセージを記録します。
  47. /// 通常は詳細なデバッグ情報の取得に使用されます。
  48. ///
  49. /// メモ: TRACEメッセージはlog4netでは「すべて」レベルで記録されます(内部的にはDebugにマッピング)。
  50. ///
  51. /// <パラメーター名='logMessage'>記録するメッセージ。
  52. 公開する override 無効 Trace(string logMessage)
  53. {
  54. // log4net には IsTraceEnabled が存在しないため、最も近い機能として IsDebugEnabled を使用しています
  55. if (logger.IsDebugEnabled)
  56. {
  57. logger.Debug(logMessage); // TRACE を内部的に DEBUG として記録
  58. }
  59. }
  60.  
  61.  
  62.     /// <概要>
  63. /// DEBUG レベルのメッセージを記録します。
  64. /// 一般的なデバッグ情報を記録し、アプリケーションの動作を診断する際にヘルプとなります。
  65. ///
  66. /// <パラメーター名='logMessage'>記録するメッセージ。
  67. 公開する override 無効 Debug(string logMessage)
  68. {
  69. if (logger.IsDebugEnabled)
  70. {
  71. logger.Debug(logMessage);
  72. }
  73. }
  74.  
  75.     /// <概要>
  76. /// INFOレベルのメッセージを記録します。
  77. /// 主に一般的なランタイム処理の際に使用されます。
  78. ///
  79. /// <パラメーター名='logMessage'>記録するメッセージ。
  80. 公開する override 無効 Info(string logMessage)
  81. {
  82. if (logger.IsInfoEnabled)
  83. {
  84. logger.Info(logMessage);
  85. }
  86. }
  87.  
  88.     /// <概要>
  89. /// 注意レベルのメッセージを記録します。
  90. /// 潜在的な問題や予期しない状況を示しますが、エラーとは異なります。
  91. ///
  92. /// <パラメーター名='logMessage'>記録するメッセージ。
  93. 公開する override 無効 Warn(string logMessage)
  94. {
  95. if (logger.IsWarnEnabled)
  96. {
  97. logger.Warn(logMessage);
  98. }
  99. }
  100.  
  101.     /// <概要>
  102. /// エラーレベルのメッセージを記録します。
  103. /// アプリケーションの継続実行が可能なエラー処理に使用します。
  104. ///
  105. /// <パラメーター名='logMessage'>記録するメッセージ。
  106. 公開する override 無効 エラー(string logMessage)
  107. {
  108. if (logger.IsErrorEnabled)
  109. {
  110. logger.エラー(logMessage);
  111. }
  112. }
  113.  
  114.     /// <概要>
  115. /// SEVEREレベルのメッセージを記録します。
  116. /// 重大なエラーとして扱われ、log4netのFATALレベルに[SEVERE]接頭語を付与して記録されます。
  117. ///
  118. /// <パラメーター名='logMessage'>記録するメッセージ。
  119. 公開する override 無効 Severe(string logMessage)
  120. {
  121. if (logger.IsFatalEnabled)
  122. {
  123. logger.Fatal('[SEVERE] ' + logMessage);
  124. }
  125. }
  126. }

すでにSDKのログレベルを定義しており、さらにSDKをカスタムloggerで初期化した場合、カスタムloggerのログレベルがPageSense SDKのログレベルよりも優先されます

ユーザー Storage サービス

ユーザー Storage サービス(USS)は、プロジェクト内で異なるA/Bテスト実験を通じてユーザーのバリエーション割り当てを永続的に保存できる外部ストレージ機構です。この機能は、プロジェクトの設定が変更された場合でも、ユーザーが同じバリエーションを継続して表示できるように一貫したバリエーションの割り当てを保証したい場合に特に役立ちます。

このような設定変更には、以下が含まれます:
  1. 新規バリエーションの追加
  2. 実験トラフィックの割り当て調整
  3. バリエーション間のトラフィック分割の調整

ユーザー Storage サービスを利用することで、ユーザー体験を維持し、A/B テスト実験結果の整合性を長期間保つことができます。USS の利用は任意です。有効化するには、UserStorageServiceインターフェースを実装し、その実装インスタンスを addUserStorageService 関数を使って PageSense SDK に渡してください。

例 コード

  1. PageSenseClient pageSenseClient = PageSenseClientBuilder.GetBuilder(projectSettings).AddUserStorageService(userStorageService).BuildClient();
上記の例では、userStorageServiceは UserStorageService インターフェースを実装したユーザー定義のクラスインスタンスです。

パラメーター詳細

Param
種類
説明
userStorageService
UserStorageService を実装したクラスのインスタンス
FullStack A/B テスト実験においてユーザーのバリエーション割り当てを永続的に管理するためのカスタム実装

例 コード

  1. using System;
  2. using System.コレクション.Concurrent;
  3.  
  4. /// <概要>
  5. /// メモリ内の並列ストレージを使用した UserStorageService インターフェースの実装。
  6. ///
  7. 公開する クラス IntegratedUserStorageService : UserStorageService
  8. {
  9.     /// <概要>
  10. /// スレッドセーフなディクショナリを使用したユーザー権限の保存。
  11. ///
  12. 非公開 readonly ConcurrentDictionary userProfileStorage = 新規 ConcurrentDictionary ();
  13.  
  14.     /// <概要>
  15. /// 指定されたユーザーIDに対するユーザー権限JSON文字列を検索します。
  16. ///
  17. /// <パラメーター名='userId'>ユーザーのID。
  18. /// <返品>ユーザー権限のJSON文字列、または見つからない場合はnull。
  19. /// userIdがnullまたは空の場合にスローされます。
  20. 公開する override string LookUp(string userId)
  21. {
  22. // ユーザーIDの認証
  23. if (string.IsNullOrWhiteSpace(userId))
  24. {
  25. throw 新規 ArgumentException('ユーザーIDはnullまたは空であってはなりません');
  26. }
  27.  
  28. string 値;
  29. 返品する userProfileStorage.TryGetValue(userId, 出力 値) ? 値 : null;
  30. }
  31.  
  32.     /// <概要>
  33. /// ユーザー権限をインメモリストレージに保存します。
  34. ///
  35. /// <パラメーター名='userProfile'>ユーザー権限オブジェクト。
  36. /// userProfile または ユーザーID が null または空の場合にスローされます。
  37. /// 保存時にエラーが発生した場合にスローされます。
  38. 公開する override 無効 保存(IUserProfile userProfile)
  39. {
  40. if (userProfile == null || string.IsNullOrWhiteSpace(userProfile.GetUserId()))
  41. {
  42. throw 新規 ArgumentException('UserProfile または ユーザーID は null または空にできません');
  43. }
  44.  
  45. try
  46. {
  47. // ユーザー権限のJSON文字列を取得
  48. string userProfileJSON = userProfile.GetUserProfileJSONString();
  49.  
  50. // ユーザー権限のJSON文字列を保存
  51. userProfileStorage[userProfile.GetUserId()] = userProfileJSON;
  52. }
  53. catch (Exception ex)
  54. {
  55. throw 新規 Exception('ユーザー権限の保存に失敗しました: ' + ex.メッセージ, ex);
  56. }
  57. }
  58. }


このドキュメントが作業の手助けとなれば幸いです。ご不明点や追加のご説明が必要な場合は、いつでもサポート窓口までメール(サポート@zohopagesense.com)でご連絡ください。