インストールスクリプトのコンポーネント

Pendoをアプリケーションに直接実装するには、以下の主要コンポーネントが必要です。

• Pendoエージェント。通常はサーバー（Pendo）側でホストされます。このようにしてPendoを利用できるようになります。
• アプリケーション（クライアント側）コードに追加するインストールスクリプト。インストールスクリプトは以下の内容で構成されています。
  • Pendoエージェントの呼び出し。
  • アカウントのアプリ（API）キー。
  • 初期化メソッド。Pendoエージェントをアクティブ化し、IDとメタデータを定義します。

この記事では、これらのコンポーネントについて簡単にまとめ、その仕組みについての簡単な技術概要を説明します。IDとメタデータの選択からユーザーの追加、Pendoの使用開始までの、Pendoを実装する主な手順については、Pendoのアプリへの直接実装を計画するを参照してください。インストールスクリプトを使ったPendoのインストールと設定については、インストールスクリプトを使用したPendoの実装に関する開発者ガイドを参照してください。

仕組み

開発者はインストールスクリプトをページヘッダーに挿入する必要があります。インストールスクリプトのすべての要素を、データを収集するすべてのページに配置する必要があります。これには、Pendoエージェントの呼び出し、アカウントを識別するためのアプリ（API）キー、Pendoエージェントを起動しIDとメタデータを定義するための初期化メソッドが含まれます。

モバイル開発者がSDKをアプリに追加し、アプリの読み込み時にPendoを初期化し、データ収集とガイドの表示の準備ができ次第訪問者を識別します。

インストールスクリプトによるインストールと設定を行ってから、そのデータを受け取るまでに最大1時間かかる場合があります。分析に利用されるデータの多くは、1時間ごとに一括集計されるため、Pendoに表示されるまでには、毎正時から最大15分かかる可能性があります。

Pendoエージェント

サブスクリプションに応じて、Pendoエージェントは次の目的でブラウザで実行されるJavaScriptファイル（pendo.js）となります。

• 訪問者イベント（ページの読み込み、機能のクリックなど）の収集および追跡
• 訪問者およびアカウントのメタデータの収集
• ガイドの読み込み
• Feedbackモジュールの配信

通常、エージェントはPendoサーバー上で構成され、クライアント側のインストールスクリプトによって要求されます。

インストールスクリプト（「スニペット」）

インストールスクリプトは、Pendoエージェントコード（pendo.js）を取得して読み込む短いJavaScript関数で、使用状況の追跡、フィードバックの収集、メッセージやガイドの配信を行うことができます。インストールスクリプトには以下が含まれます。

• Pendoエージェントの要求
• エージェントが収集したデータをPendoサブスクリプションのプロダクトにマッピングする顧客固有のアプリキー
• Pendoエージェントをアクティブにするために必要な初期化メソッド

Pendoエージェントが機能するには、インストールスクリプトと初期化メソッドがウェブサイトのすべてのページに存在する必要があります。ただし、アプリケーションにトップフレームと同じドメインからの子フレームがある場合は除きます。この場合、インストールスクリプトをアプリケーションのトップフレームに追加することで、Pendoを子フレームに自動的にインストールするようにインストールスクリプトを設定することができます。これらのフレームのいずれかで訪問者IDまたはメタデータに加えられた変更は、すべてのフレームに適用されます。

注：インストールスクリプトが存在しても、トラッキングが行われることにはなりません。トラッキングを行うには、インストールスクリプトを初期化する必要があります。詳しくは、初期化メソッドをご覧ください。

アプリ（API）キー

インストールスクリプトは、Pendoをライブラリとして読み込み、その機能をウィンドウレベルで使用できるようにし、コードブロックに含まれる32桁のアプリ（API）キーを渡します。アプリキーは、サブスクリプション内の特定のアプリケーションに関連付けられるために、Pendoに送信されるデータを識別します。

これは秘密鍵ではなく、セキュリティやプライバシーとは無関係です。アプリキーはPendoサブスクリプションにデータを送信するためだけに使用され、データの読み取りアクセスはできません。

アプリキーを見つけるには、次の操作を行います。

1. ［設定（Settings）］>［サブスクリプション設定（Subscription Settings）］の順に進みます。
2. ［アプリケーション］タブを開きます。
3. リストからアプリケーションを選択します。

アプリキーは、サブスクリプションのアプリの詳細にすでに入っており、［アプリの詳細（App Details）］、または［インストール設定（Install Settings）］にあるインストールスクリプトの最下部で見つけられます。

初期化メソッド

使用状況分析の追跡、フィードバックの収集、およびガイドの提供を開始する前に、Pendoエージェントを初期化する必要があります。初期化は、次の場合のPendoインストールスクリプトのJavaScript関数です。

• 訪問者IDおよびアカウントIDとして渡したい値を決定します。
• Pendoに提供するメタデータをカスタマイズします。
• Pendo Feedbackの自動タグを作成します。詳しくは、Feedbackにおける自動タグ付けをご覧ください。

初期化コードブロックを使用すると、訪問者とアカウントを特定して、アナリティクスをグループ化したり、アプリケーション変数（ユーザーオブジェクトなど）からの情報を使用してガイドをターゲティングしたり、Feedbackリクエストに自動的にタグ付けしたりすることができます。

pendo.initalize()が実行される前に、インストールスクリプトに渡されるすべての変数を定義する必要があります。Pendoに渡されたすべての変数が初期化時に存在しない場合、Pendoは正しく初期化されません。 詳細については、条件付きでPendoを初期化するを参照してください。

初期化は、訪問者が認証された後のウィンドウの再読み込みごと、またはサイトにiframeがある場合はフレームごとに実行する必要があります。複数ページのアプリケーションを使用している場合はログインページだけでなく各ページ、またはグローバルテンプレートがある場合はそのページで、Pendoを初期化する必要があります。

以下は初期化コードブロックの例です。これは［インストール（Install）］ページまたは［アプリの設定（App Settings）］にあります。この例をカスタマイズして、サブスクリプションのニーズを満たすことができます。

pendo.initialize({
    visitor: {
        id:              'visitor-id-goes-here'   // Required if user is signed in
        // email:        // Recommended if using Pendo Feedback or NPS Email
        // full_name:    // Recommended if using Pendo Feedback
        // role:         // Optional

        // You can add any additional visitor-level key values here,
        // as long as it's not one of the above reserved names.
    },

    account: {
        id:           'account-id-goes-here' // Highly recommended; required if using Pendo Feedback
        // name:         // Optional
        // is_paying:    // Recommended if using Pendo Feedback
        // monthly_value:// Recommended if using Pendo Feedback
        // planLevel:    // Optional
        // planPrice:    // Optional
        // creationDate: // Optional

        // You can add any additional account-level key values here,
        // as long as it's not one of the above reserved names.
    }
});