SDKのカスタマイズ

SDKのカスタマイズ

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

PageSense SDKは、開発者がアプリケーションのニーズに合わせて動作を調整できる柔軟な設定モデルを提供します。SDKは初期設定のまま最小限のセットアップで使用できますが、パフォーマンス、ログ記録、ストレージに関する要件が厳しいアプリケーションでは、SDK内のコンポーネントを個別に設定することで、より効果的に活用できます。

初期設定による初期化

カスタムオプションを設定せずにPageSense SDKを初期化すると、一般的な用途向けに事前設定された値を使用して、PageSenseClientインスタンスが自動的に作成されます。  

  • ポーリング間隔：PageSense SDKはPageSenseサーバーに定期的に接続し、最新のプロジェクトの設定を取得します。初期設定では、この間隔は10秒に設定されており、手動で更新しなくても、プロジェクトの設定に対する最新の変更がアプリケーションに反映されます。

  • ログレベル：SDKは、INFO以上のレベルのログメッセージを記録します。対象には、主要な動作イベント、警告、エラー、重大度の高いメッセージが含まれます。

  • ロガー：初期設定ではコンソールロガーが組み込まれており、アプリケーションの出力コンソールにログを直接表示できます。

これらの初期設定パラメーターは、すばやく利用を開始し、一般的な開発環境、テスト環境、本番環境で安定した動作を実現できるように設計されています。

カスタマイズ可能なオプション  

より高度な制御が必要なアプリケーション向けに、PageSense SDKには初期化時に使用できる設定用フックが複数用意されています。これにより、SDKと環境との連携方法を細かく調整できます。  

 

オプション

目的

ポーリング間隔

SDKがPageSenseサーバーと同期する頻度を制御します。この値を調整することで、ネットワークの使用状況を最適化したり、プロジェクトの設定の更新に対する応答性を高めたりできます。

カスタムログ

カスタムロガーを使用して、希望する形式でSDKのログを記録したり、一元管理されたログシステムに送信したりできます。

カスタムユーザーストレージ

ユーザーに割り当てられたテストのバリエーションを保持する方法を、アプリケーション側で設定できます。セッションやデバイスが変わっても一貫したユーザーエクスペリエンスを維持する必要がある場合に役立ちます。

ログレベル

出力するログメッセージを細かく制御できます。アプリケーションのデバッグまたは監視基準に合わせて、TRACE、DEBUG、INFO、WARN、ERROR、SEVEREなどのスタンダードなレベルを選択できます。

 

PageSense SDKでは、ビルダーパターンを使用して、PageSenseClientの作成時にカスタム設定を適用します。ポーリング間隔、ログレベル、カスタムロガー、カスタムユーザーストレージなどの任意の設定は、PageSenseClientBuilderに指定します。設定が完了すると、PageSenseClientBuilderは、カスタマイズしたこれらのパラメーターを使用してPageSenseClientインスタンスを構築します。この方法により、すべての設定ロジックが一元化され、設定が不完全なクライアントが作成されるリスクを回避できます。また、アプリケーションの要件に応じてSDKの動作を調整するための簡潔で拡張性の高い仕組みを利用できます。

次のコードでは、PageSenseClientBuilderを使用して、カスタマイズしたPageSenseClientインスタンスを作成する方法を説明します。
  1. use Zoho\PageSense\PageSenseClientBuilder;
  2. // プロジェクトの設定を使用してビルダーを作成します。
  3. $builder= PageSenseClientBuilder::getBuilder($projectSettings);
  4.  
  5. // 任意のカスタム設定を適用し、PageSenseClientを構築します。
  6. $pageSenseClient = $builder
  7. ->addPollingInterval(60000) // ポーリング間隔を60秒に設定します
  8. ->addLogLevel('DEBUG') // DEBUG以上のレベルのログを取得します
  9. ->addCustomLogger($customLogger) // PSR-3互換のカスタムロガーを使用します
  10. ->addCustomStorage($customStorage) // カスタムユーザーストレージサービスを設定します
  11. ->buildClient(); // 設定済みのクライアントインスタンスを構築して返します

ポーリング間隔  

PageSense SDKには、addPollingIntervalメソッドが用意されています。このメソッドを使用すると、PageSense SDKがプロジェクトの設定の更新をPageSenseサーバーに確認する頻度を制御できます。このポーリング機能により、テストの更新、トラフィックの再配分、バリエーションや目標の変更など、対象プロジェクトで行われたPageSenseの最新の変更とSDKが同期されます。

初期設定では、PageSense SDKはPageSenseサーバーを10秒ごとにポーリングします。別の更新頻度が必要なアプリケーションでは、addPollingIntervalメソッドにミリ秒単位の値を指定して、間隔を変更できます。

使用例

  1. // プロジェクトの設定を使用してビルダーを作成します。
  2. $builder= PageSenseClientBuilder::getBuilder($projectSettings);\
  3. // ポーリング間隔を1秒に設定し、PageSenseClientを構築します。
  4. $pageSenseClient = $builder->addPollingInterval(60000)->buildClient();
Notesこの例では、ポーリング間隔を60,000ミリ秒（60秒）に設定しています。これにより、SDKは1分に1回、最新のプロジェクトの設定をPageSenseサーバーに要求します。

メソッドのパラメーター

パラメーター

種類

説明

pollingInterval

整数

SDKがPageSenseサーバーをポーリングする頻度をミリ秒単位で指定します。


ポーリング間隔を選択する際の考慮事項

適切なポーリング間隔は、アプリケーションのパフォーマンス要件、使用パターン、プロジェクトの設定反映の遅延に対する許容度に応じて選択します。

 

次の点に注意してください。

 

1. 非常に短い間隔（10秒未満）

  • PageSenseサーバーへの要求数が増加します。

  • ネットワークのオーバーヘッドが増加する可能性があります。

  • プロジェクトの設定を変更する頻度が低い場合、不要な負荷が発生する可能性があります。

 

2. 中程度の間隔（10～60秒）

  • リアルタイムまたはほぼリアルタイムでの使用に適しています。

  • 応答性とネットワーク効率のバランスを保つことができます。

 

3. 長い間隔（5分超）

  • ネットワークトラフィックは減少しますが、PageSenseからの更新が遅れる可能性があります。

  • 次のポーリングサイクルまで、古いテスト設定やターゲティング設定がユーザーに適用され、テスト結果に影響する可能性があります。

ベストプラクティス

  • プロジェクトの設定変更をすぐに反映する必要がある場合は、短い間隔を選択します。

  • ネットワーク使用量の削減を優先する高トラフィックのアプリケーションでは、長い間隔を使用します。

予想されるプロジェクトの設定の更新頻度、アプリケーションの負荷、サーバーの処理能力に応じて、間隔を調整します。

ログレベル  

PageSense SDKには、アプリケーションの実行中にPageSense SDKが出力するログ情報の量を設定できるaddLogLevelメソッドがあります。SDKの内部処理を詳しく確認する必要がある場合や、本番環境でログ出力を制限する場合に役立ちます。

ログレベルを指定すると、SDKが出力するメッセージの最低重大度が設定されます。指定したレベル以上の重大度を持つすべてのメッセージが記録されます。これにより、SDKに組み込まれたログ記録システムの出力量を細かく制御できます。

ログレベルはString型で渡す必要があり、SDKでは次の値を指定できます。TRACE, DEBUG, INFO, WARNING, ERROR, SEVERE

これらのレベルは、各種アプリケーションフレームワークで使用される一般的なログ記録基準に対応しています。

使用例

  1. use Zoho\PageSense\PageSenseClientBuilder;
  2. // プロジェクトの設定を使用してビルダーを作成します。
  3. $builder= PageSenseClientBuilder::getBuilder($projectSettings);
  4. // 個別指定のログレベルを適用し、PageSenseClientを構築します。
  5. $pageSenseClient = $builder->addLogLevel('DEBUG')
                                                          ->buildClient();
Warning上記の例では、ログレベルが'WARNING'に設定されています。そのため、PageSense SDKは次のレベルに分類されるログメッセージを出力します。WARNING、ERROR、SEVERE。

メソッドのパラメーター

パラメーター

種類

説明

logLevel

String

記録するログの最低重大度を指定します。

 

カスタムロガー  

PageSense SDKには、診断メッセージや動作メッセージをコンソールに記録するロガーが組み込まれています。ただし、多くのアプリケーションでは、独自の一元管理型またはフレームワーク固有のログ記録システムを使用しています。このような環境に対応するため、PageSense SDKでは、標準のログ記録処理を置き換えるカスタムロガーの実装を使用できます。

 

カスタムロガーを登録すると、SDKによって生成されるすべての重大度レベルのログ出力が、その実装を経由するようになります。これにより、独自のログ記録ポリシー、書式設定ルール、転送ロジック、保存方法を適用できます。

カスタムロガーは、特に次の場合に役立ちます。

  • アプリケーションですでに構造化または一元管理されたログ記録フレームワークを使用している場合。

  • ログを外部の監視ツールに転送する必要がある場合。

  • システム内のすべてのモジュールでログ出力を統一する場合。

カスタムロガーを使用するには

カスタムロガーを連携するには、PageSenseLoggerインターフェースを実装したクラスのインスタンスを指定する必要があります。このインターフェースでは、SDKがログメッセージの表示と保存に使用するメソッドを定義します。実装内では、任意のログ記録ライブラリー（Monolog、Log4j、Winstonなど）を使用したり、選択した場所にログを書き込んだりできます。ロガークラスの準備ができたら、PageSenseClientBuilderで使用できるaddCustomLoggerメソッドを使用してSDKに登録します。
Notesメモ：PageSense SDKの初期化でaddLogLevel()とaddCustomLogger()の両方を使用する場合、カスタムロガーに設定されたログレベルが、SDKに指定されたログレベルより優先されます。PageSense SDKは内部のログレベルフィルターを適用せず、すべてのログメッセージをカスタムロガーに転送します。

使用例

  1. use Zoho\PageSense\PageSenseClientBuilder;
  2.  // カスタムロガーを作成する
  3. $customLogger = new FileSystemLogger();
  5. // プロジェクトの設定を使用してビルダーを作成する。
  6. $builder = PageSenseClientBuilder::getBuilder($projectSettings);
  7.  
  8. // カスタムログレベルを適用してPageSenseClientをビルドする。
  9. $pageSenseClient= $builder->addCustomStorage($customLogger)->buildClient();

上記の例のcustomLoggerは、PageSenseLoggerインターフェースを実装し、任意のログ記録ロジックを備えた、アプリケーションで定義されたオブジェクトです。

 

メソッドのパラメーター 

パラメーター

型

説明

customLogger

次のインターフェースを実装するクラスのインスタンス：PageSenseLogger

 

SDKのログメッセージを記録する方法と場所を決定する、ユーザー定義のロガーです。

 

 

このドキュメントには、 PageSenseLoggerインターフェースを、 Analog Logging Framework を使用して実装し、PageSense SDKと連携させる方法を示すサンプルの添付ファイルが含まれています。

ユーザーストレージサービス（USS）  

ユーザーストレージサービス（USS）を使用すると、PageSense SDKは、プロジェクト内の複数のA/Bテストにわたってユーザーへのバリエーションの割り当てを保持できます。カスタムストレージ方式を使用することで、プロジェクトやテストの設定を変更した場合でも、ユーザーに継続して同じバリエーションを表示できます。

この機能は、プロジェクトの設定を変更した場合でも、バリエーションの割り当ての一貫性を維持し、安定したユーザーエクスペリエンスを提供するうえで特に有効です。対象となる主なケースは次のとおりです。

  • 新規バリエーションの導入

  • テストのトラフィックの割り当ての変更

  • バリエーション間でのトラフィックの割り当て先の移動

  • 環境間でのプロジェクトの設定の移行

仕組み  

USSを有効にするには、PageSense SDKが公開するUserStorageServiceインターフェースを独自に実装します。このインターフェースでは、PageSense SDKによる次の処理方法を定義します。

  • ユーザーに割り当てられたバリエーションを保存する

  • 以降のAPIリクエストで、保存されたバリエーションを取得する

アプリケーションに適した任意のストレージ方式を使用できます。例は次のとおりです。

  • ローカルファイル

  • リレーショナルデータベースまたはNoSQLデータベース

  • Redisなどのインメモリーキャッシュ

  • 分散セッションストア

  • アプリケーションレベルのカスタム永続化システム

実装後、個別指定のストレージサービスは、PageSense SDKのaddUserStorageServiceメソッドを使用してPageSenseClientBuilderに指定します。

使用例
  1. use Zoho\PageSense\PageSenseClientBuilder;
  2. // 個別指定のストレージファイルを保存するパス
  3. $storageDirectory = __DIR__. '/UserStorage';
  4.  
  5. // 個別指定のユーザーストレージを作成
  6. $customStorage = new FileUserStorageService($storageDirectory);
  7. // プロジェクトの設定を使用してビルダーを作成。
  8. $builder = PageSenseClientBuilder::getBuilder($projectSettings);
  9.  
  10. // 個別指定のログレベルを適用し、PageSenseClientをビルド。
  11. $pageSenseClient = $builder->addCustomStorage($customStorage)->buildClient() ;
上記の例は、個別指定のユーザーストレージサービスをPageSense SDKと連携する方法を示しています。ここでは、指定したディレクトリーにバリエーションの割り当てを保持するため、ファイルベースのストレージ実装を使用しています。

メソッドのパラメーター

パラメーター

種類

説明

userStorageService

UserStorageServiceを実装するクラスのインスタンス

フルスタックA/Bテストでユーザーごとのバリエーション割り当てを継続的に管理するための個別指定の実装

このドキュメントには、PageSense SDK向けにファイルベースのストレージ機能を使用してUserStorageServiceのインターフェイスを実装する方法を示すサンプルファイルが添付されています。

 ベストプラクティス   

1. リアルタイム更新のためのWebhookの使用  

本番環境では、ポーリング間隔を極端に短くしないでください。高頻度のポーリングにより、使用しているインフラストラクチャーやPageSenseのサーバーに不要な負荷がかかる可能性があります。Webhookを使用すると、ほぼリアルタイムの設定更新をより効率的に行えるため、可能な場合はWebhookを優先してください。

2. 認証済みユーザーに対するユーザーストレージサービスの使用  

USSは、ユーザーIDなどの固定識別子がユーザーに割り当てられている場合にのみ有効にしてください。これにより、複数のセッションにわたって一貫したバリエーションを割り当てられます。匿名または一時的なトラフィックでは、通常、USSのメリットは限られており、回避可能なオーバーヘッドが発生する場合があります。

3. SDKキーの保護  

sdkKeyは必ずサーバー上でのみ管理してください。次の場所では公開しないでください。

  • ブラウザー側のJavaScript

  • 公開リポジトリー

  • モバイルアプリケーション

  • クライアント向けAPIのレスポンス

これにより、プロジェクトの設定への不正アクセスを防止できます。

4. 標準のログ記録／キャッシュインターフェイスの採用  

SDKを確立された次のPHP標準と連携します。

  • PSR-3：ログ記録用

  • PSR-16：キャッシュ用（任意。USSまたはその他の永続化レイヤーと併用する場合）

これらの標準に準拠することで、予測可能な動作が確保され、一般的なPHPフレームワークと容易に連携できます。

5. ロガーの優先順位ルール  

addLogLevel()とaddCustomLogger()の両方を指定した場合は、個別指定のロガーに組み込まれたフィルタリング処理が優先されます。SDK側で追加のフィルタリングを行わず、すべてのログメッセージをロガーに転送します。

6. バリエーション割り当てに使用する固定識別子の確保  

バリエーションの評価には、永続的なユーザーIDなど、一貫した不変の識別子を使用してください。IPアドレスやセッションIDなど、頻繁に変更される識別子は使用しないでください。

7. Webhookエンドポイントの保護と検証  

Webhookを使用する場合。

  • 受信した要求を検証する

  • Webhookエンドポイントへのアクセスを制限する

  • エンドポイントへの到達性と耐障害性を確保する

これにより、設定の更新が確実に配信されます。

8. USSと個別指定ロガーでの軽量な実装の使用  

UserStorageServiceとPageSenseLoggerの実装は、要求の処理に遅延が生じないよう、効率的かつノンブロッキングにする必要があります。

 注意事項   

1. 過剰なポーリングの回避  

ポーリング間隔が短すぎる場合（10秒未満）、次の問題が発生する可能性があります。

  • サーバー負荷の増加

  • 過剰なネットワークトラフィック

  • PageSenseエンドポイントへの不要な負荷

本番環境では慎重に使用してください。

2. 長いポーリング間隔による設定更新の遅延  

ポーリング間隔が数分を超える場合、次の問題が発生する可能性があります。

  • テストの更新の反映の遅延

  • 次のポーリングサイクルまで、古いバリエーションロジックがユーザーに適用される

アプリケーションの要件に応じて、ポーリング間隔を慎重に調整してください。

3. 永続ストレージでの適切な障害処理  

USSを使用する場合、ストレージ機構が次の処理に対応できることを確認してください。

  • 読み取りや書き込みの失敗への対応

  • 不完全な書き込みからの復旧

  • ファイルシステムやデータベースのエラーの処理

これにより、バリエーションの割り当ての不整合を防止できます。

 デバッグとトラブルシューティング   

1. ステージング環境でのDEBUGログの有効化  

本番環境以外では、次の項目を確認するため、ログレベルをDEBUGに設定します。

  • バリエーションの割り当て

  • バケットの分布

  • Webhookとポーリングの活動

  • SDKの初期化の詳細

問題を診断する場合を除き、本番環境ではDEBUGログを有効にしないでください。

2. テスト中のバリエーション割り当ての記録  

ロールアウト中にバリエーションの割り当てを記録すると、次の項目を検証できます。

  • ハッシュ処理の一貫性

  • 正しいトラフィックの割り当て

  • 環境間の整合性（開発→QA→本番） 

3. USSの動作の徹底的なテスト  

次のような状況をシミュレーションします。

  • テストの更新

  • 新規バリエーション

  • トラフィックの再割り当て

  • テストの再開

保存されたバリエーションが引き続き正しく決定されるか、意図どおり更新されることを確認してください。

4. Webhook配信の検証  

次の項目を確認します。

  • サーバーへの到達性

  • ファイアウォールルール

  • Webサーバーのログ

  • PageSenseによる再試行（30秒ごと、最長15分）

Webhookでエラーが発生すると、設定が適時に更新されない可能性があります。

5. ポーリング動作の確認  

次の点を確認してください。

  • ポーリングスレッドが有効である

  • ポーリング間隔が正しく設定されている

  • ネットワークエラーが適切に処理される

Webhookを利用できない場合、ポーリングをフォールバックとして使用する必要があります。

6. ビルダーの設定順序の検証  

buildClient()を呼び出す前に、すべての設定オプション（ポーリング間隔、ログレベル、個別指定ロガー、USS）がビルダーに適用されていることを確認してください。

7. PHP環境の制約の確認  

ホスティング環境が次の要件に対応していることを確認してください。

  • ファイルシステムの権限（ファイルベースのUSSを使用する場合）

  • 十分なメモリー上限

  • 必要なPHP拡張機能（例：cURL、JSON、OpenSSL）

環境の問題がSDKの動作に影響する可能性があります。

このドキュメントが、作業を円滑に進めるうえでお役に立てば幸いです。詳しい説明が必要な場合やご質問がある場合は、support@zohopagesense.comまでお気軽にメールでお問い合わせください。