SDKのカスタマイズ

SDKのカスタマイズ

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

PageSense SDK は柔軟な構成モデルを提供しており、開発者はアプリケーションの要件に合わせて 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 分ごとに PageSense サーバーから最新のプロジェクト設定を取得します。

メソッドのパラメーター

Parameter

種類

説明

pollingInterval

Integer

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


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

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

 

次のポイントを考慮してください。

 

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

  • PageSense サーバーへのリクエスト数が増加します。

  • ネットワークのオーバーヘッドが大きくなる可能性があります。

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

 

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

  • 多くのリアルタイムまたは準リアルタイムのユースケースに適しています。

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

 

3. 長い間隔（5 分超）

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

  • 次回のポーリングまで、ユーザーが古い実験やターゲティング設定を適用されたままになる場合があり、実験結果に影響する可能性があります。

ベストプラクティス

  • プロジェクト設定の変更をすばやく反映させることが重要な場合は、短めの間隔を選択します。

  • ネットワーク使用量の最小化が優先される高トラフィックなアプリケーションでは、長めの間隔を使用します。

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

ログレベル  

PageSenseSDK には addLogLevel メソッドが用意されており、アプリケーション実行中に PageSense SDK が出力するログ情報の量を指定できます。これは、SDK の内部処理をより詳細に把握したい場合や、本番環境でのログ出力を制限したい場合に役立ちます。

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

ログレベルはString型で渡す必要があり、SDK では次の値を受け付けます：TRACE, DEBUG, INFO, 注意, エラー, SEVERE

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

使用例

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

メソッドパラメーター

Param

種類

説明

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 は 1 つのプロジェクト内で複数の A/B テスト実験にわたり、ユーザーのバリエーション割り当てを永続化できます。カスタムのストレージメカニズムを提供することで、プロジェクトや実験の設定が変更された場合でも、ユーザーが常に同じバリエーションを受け取れるようにできます。

この機能は、プロジェクト設定が変更された場合でも、バリエーション割り当ての一貫性を維持し、安定したユーザー体験を提供するうえで特に有用です。一般的なユースケースには次のようなものがあります。

  • 新しいバリエーションの追加

  • 実験のトラフィック配分の変更

  • バリエーション間のトラフィック分配の再調整

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

動作方法  

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

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

  • 取得：後続の API リクエスト時に保存済みバリエーションを取得する方法

実装では、次のようにアプリケーションに適した任意のストレージメカニズムを使用できます。

  • ローカルファイル

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

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

  • 分散セッションストア

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

実装が完了したら、カスタムストレージサービスをPageSense SDK に対して、PageSenseClientBuilder の addUserStorageService メソッドを通じて渡します。

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

メソッドパラメーター

Param

種類

説明

userStorageService

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

FullStack A/B テスト実験において、ユーザーごとのバリエーション割り当てを永続的に管理するためのカスタム実装

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

 ベストプラクティス   

1. リアルタイム更新には Webhook を使用する  

本番環境では、ポーリング間隔を極端に短く設定しないでください。高頻度のポーリングは、お客様のインフラストラクチャおよび PageSense サーバーに不要な負荷を発生させます。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 とカスタム Logger には軽量な実装を使用する  

UserStorageService と PageSenseLogger の実装は、リクエスト処理に遅延を発生させないよう、高速かつノンブロッキングである必要があります。

 警告   

1. ポーリングのしすぎを避ける  

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

  • サーバー負荷の増加

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

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

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

2. ポーリング間隔が長すぎると構成更新が遅延する  

ポーリング間隔が数分以上になると、次のような結果を招く可能性があります。

  • 実験更新の反映遅延

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

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

3. 永続ストレージは障害を適切に処理する必要がある  

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

  • 読み取り/書き込みエラーの処理

  • 部分的な書き込みからの復旧

  • ファイルシステムまたはデータベースエラーの管理

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

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

1. ステージング環境で DEBUG ログを有効にする  

本番以外の環境では、ログレベルを DEBUG に設定し、次の内容を確認します。

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

  • バケット分布

  • Webhook およびポーリングの動作

  • SDK 初期化の詳細

問題の診断時を除き、本番環境で DEBUG ログを有効にすることは避けてください。

2. テスト中にバリエーションの割り当てをログに記録する  

ロールアウト中にバリエーションの割り当てを記録しておくと、次の点を検証するのに役立ちます。

  • ハッシュの一貫性

  • 正しいトラフィック配分

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

3. USS の動作を十分にテストする  

次のようなシナリオをシミュレートします。

  • 実験の更新

  • 新しいバリエーションの追加

  • トラフィックの再配分

  • 実験の再実行

保存されたバリエーションが正しく解決され続けるか、または想定どおりに更新されることを確認してください。

4. Webhook 配信を確認する  

次の点を確認します。

  • サーバーへ到達可能であること

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

  • Web サーバーログ

  • PageSense による再試行（30 秒間隔、最大 15 分間）

Webhook の失敗は、構成更新の遅延につながる可能性があります。

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

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

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

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

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

Webhook が利用できない場合のフォールバックとして、ポーリングを使用するようにしてください。

6. ビルダー構成の順序を確認する  

polling interval、log level、カスタム logger、USS など、すべての構成設定が buildClient() を呼び出す前にビルダーへ適用されていることを確認してください。

7. PHP 環境の制約を確認する  

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

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

  • 十分なメモリ上限

  • 必須の PHP 拡張機能（例：cURL、JSON、OpenSSL）

環境上の問題は、SDK の動作に影響を与える可能性があります。

このドキュメントが、設定作業の一助となれば幸いです。ご不明点や追加の説明が必要な場合は、いつでも support@zohopagesense.com までメールでお問い合わせください。