この記事では、アカウントレベルのプロダクトエンゲージメントスコア（PES）データを、定着率、粘着率、成長率とともに、APIを使ってGoogleスプレッドシートに直接エクスポートする方法を説明します。Googleスプレッドシートにエクスポートすることで、PESをアカウントレベルで簡単に分析したり、Pendoへのアクセス権のない他のユーザーやチームメンバーにこのデータを共有したりすることが可能になります。
この結果生成されるレポートには、アカウントIDごとに1行が記録されます。各行の個別の列には、該当するアカウントIDの粘着率、成長率、定着率、および全体のPESスコアが記録されます。
重要：この記事で紹介されている方法を参考にして、APIコールをカスタマイズし、Googleスプレッドシートで詳細なレポートを作成することは可能ですが、これはカスタムコードに該当するため、Pendoのテクニカルサポートの対象外となります。対象外のサポートが必要な場合は、まずPendoのアカウント担当者がその評価を実施します。場合によっては、さらにPendoのプロフェッショナルサービスチームが有償で対応することになります。
要件
以下のガイドラインに進む前に、次のことを確認してください。
- APIアクセスがPendoの契約に含まれていること。ご不明な点があれば、Pendoのアカウント担当者までお問い合わせください。
- インテグレーションキーを保有していること。これはPendoスニペットに表示されるキーではありません。また、管理者のみがインテグレーションキーを作成できます。Pendo Engageでインテグレーションキーを作成するには、［設定（Settings）］>［インテグレーション（Integrations）］>［インテグレーションキー（Integration Keys）］に移動し、［インテグレーションキーを追加（Add Integration Key）］を選択します。
- GoogleスプレッドシートとGoogle Apps Scriptの拡張機能へのアクセス権があること。
Googleスクリプトの作成
以下の手順に従って、訪問者またはアカウントレポートの内容をGoogleスプレッドシートに直接抽出します。
- 新しいGoogleスプレッドシートを作成します。
- 上部メニューバーから［Extensions（拡張機能）］を選択して、新しいタブで［Apps Script］開きます。
- 新しいタブでは、デフォルトでCode.gsファイルが表示されます。Googleがデフォルトで追加している空の関数を含め、すでにあるコンテンツをすべて削除し、次のテキストに置き換えます。
//----------------------------------------------------------------------------------
// スプレッドシート定数
//----------------------------------------------------------------------------------
/**
* SPREADSHEET_ID_PES：データのエクスポート先となるスプレッドシートのID。
* SHEET_NAME_PES：すべてのデータを置き換える対象となるスプレッドシートの名前。
* INTEGRATION_KEY_PES：APIから取得してヘッダーとして渡す、x-pendo-integration-key。
* APP_ID：エクスポートしようとするデータが存在するPendoアプリケーションのID。Pendoサブスクリプションにウェブアプリケーションが1つしかない場合、IDは-323232となります。これを変更する必要はありません。
* BASE_URL_PES：USインスタンス（app.pendo.io）でPendoにアクセスしている場合は、デフォルトですでに正しい値が入力されているため、アクションは一切必要ありません。PendoサブスクリプションがEUインスタンスにある場合は、BASE_URLの値を「app.eu.pendo.io」に変更します。PendoサブスクリプションがUS1インスタンスにある場合は、BASE_URLの値を「app.us1.pendo.io」に変更します。PendoサブスクリプションがJPNインスタンスにある場合は、BASE_URLの値を「app.jpn.pendo.io」に変更します。PendoサブスクリプションがUS1インスタンスにある場合は、BASE_URLの値を「us1.app.pendo.io」に変更します。
*/
const SPREADSHEET_ID_PES = "ENTER-YOUR-SPREADSHEET-ID";
const SHEET_NAME_PES = "ENTER-YOUR-SPREADSHEET-TAB";
const INTEGRATION_KEY_PES = "ENTER-YOUR-INTEGRATION-KEY";
const APP_ID = -323232; //ここでは引用符は使用しません。
const BASE_URL_PES = "app.pendo.io";
//----------------------------------------------------------------------------------
// PES構成
//----------------------------------------------------------------------------------
/** 分析する日数を入力します。例：過去180日間を分析するには「180」と入力。 */
const NUMBER_OF_DAYS = ENTER-NUMBER-OF-DAYS; //ここでは引用符は使用しません。
/** ［Pendo］>［行動（Behavior）］>［PES］>［PESを管理（Manage PES）］で表示される選択肢を入力します。具体例は以下のとおりです。Pendoの設定と一致していれば、変更する必要はありません。 */
const ADOPTION_USERBASE = "visitors";
const STICKINESS_USERBASE = "visitors";
const STICKINESS_NUMERATOR = "weekly";
const STICKINESS_DENOMINATOR = "monthly";
const STICKINESS_EXCLUDE_WEEKENDS = true; //ここでは引用符は使用しません。
const GROWTH_USERBASE = "visitors";
/***********************************************************************************
------------------------------------------------------------------------------------
------------------この下のセクションは一切変更しないでください------------------
------------------------------------------------------------------------------------
***********************************************************************************/
// これらのヘッダーは変更しないでください。これらはAPIレスポンスとPES結果のフィルタリング用です。
const PES_HEADERS = ['account', 'stickiness', 'growth', 'adoption', 'productEngagementScore'];
// 定数領域で定義されたアプリケーションのPESクエリ
const PES_QUERY = {
"response": {
"mimeType": "application/json"
},
"request": {
"name": "PES",
"pipeline": [
{
"pes": {
"appId": APP_ID,
"firstDay": "now()",
"dayCount": -1 * NUMBER_OF_DAYS, //負の数（例：-30日）
"groupBy": "account",
"config": {
"adoption": {
"userBase": ADOPTION_USERBASE
},
"stickiness": {
"userBase": STICKINESS_USERBASE,
"numerator": STICKINESS_NUMERATOR,
"denominator": STICKINESS_DENOMINATOR,
"excludeWeekends": STICKINESS_EXCLUDE_WEEKENDS
},
"growth": {
"userBase": GROWTH_USERBASE
}
}
}
}
]
}
}
/**
* PES集計結果から過去180日間の全アカウントのPESデータを取得し、結果を抽出します。
* この呼び出しでは、リクエストのappIdおよびその他の指定値を持つ事前定義されたPES_QUERYオブジェクトが使用されます。
*/
function apiCallPES_() {
let options, endpoint, response, events;
// ヘッダーに認証キー、ペイロードにjsonを含む、HTTP Postリクエスト
options = {
'method': 'post',
'payload': JSON.stringify(PES_QUERY),
"headers": {
'x-pendo-integration-key': INTEGRATION_KEY_PES,
'content-type': "application/json"
},
'muteHttpExceptions': true
};
// 集約エンドポイントで必要な詳細を取得します。
endpoint = `https://${BASE_URL_PES}/api/v1/aggregation`;
response = UrlFetchApp.fetch(endpoint, options);
// リクエストが成功した場合は処理を続行し、失敗した場合はfalseを返します。
if (response.getResponseCode() == 200) {
// Prase the response Content to JSON
pesResults = JSON.parse(response.getContentText());
// If there are one or more results, then return them; otherwise return false
if (pesResults['results'].length > 0) return pesResults['results'];
}
// リクエストに失敗した場合、またはPESの結果がない場合、falseを返します。
return false;
}
/**
* オブジェクトの配列を2次元配列に変換します。
* このとき、ヘッダーにあるキーのみを考慮し、残りは無視します。
*/
function formatDataPES_(pesResults, headers) {
let arr, arrNested;
// ヘッダーを最初のインデックスにリストとして追加します（シート内のすべての行の先頭に来るため）。
arr = [headers];
// pesResultsの各アカウントについては、それらの値を取得し、すべてをマトリックス形式で結合します。
// 新しい各アカウントが次の行に移動する場所
pesResults.forEach((accountRes) => {
arrNested = [];
headers.forEach((header) => { arrNested.push(accountRes[header]) });
arr.push(arrNested);
});
return arr;
}
/**
* きれいにフォーマットされたPESデータを取得し、シートに書き込みます。
*/
function writePESToSheet_(pesData) {
// ワークブックへのハンドルを開きます。これが見つからない場合は、このプロセスを中断します。
let workbook = SpreadsheetApp.openById(SPREADSHEET_ID_PES);
if (!workbook) {
Logger.log("WORKBOOK NOT FOUND ");
return;
}
// ワークシートへのハンドルを開きます。これが見つからない場合は、このプロセスを中断します。
worksheet = workbook.getSheetByName(SHEET_NAME_PES);
if (!workbook) {
Logger.log("WORKSHEET NOT FOUND");
return;
}
// この時点でシートに表示されているものをすべて消去します。
worksheet.getDataRange().clear();
// 新しいPESデータをシートに書き込みます。
worksheet.getRange(1, 1, pesData.length, pesData[0].length).setValues(pesData);
// 最初の行（ヘッダー行）を太字、中央揃えにし、背景を緑色にします。
worksheet.getRange(1, 1, 1, 5)
.setBackground('#DCC9F9')
.setFontWeight("bold")
.setHorizontalAlignment('center');
}
/**
*全プロセスの命令を1つのメソッドで出します。これ自体に大きな効果があるわけではありませんが、これでコードを整理しやすくなります。
*/
function mainPES() {
// 集計エンドポイントにAPI呼び出しを行い、pesDataを取得します。
let pesData = apiCallPES_();
// 成功しなかった場合、このプロセスを停止します。
if (!pesData) {
Logger.log("API Call Failed or there is no data to grab");
return;
}
// オブジェクトから2D配列に変換されたデータをフォーマットします。
pesData = formatDataPES_(pesData, PES_HEADERS);
// 2D ARRをスプレッドシートタブに書き込みます。
writePESToSheet_(pesData);
} - 12行目から32行目にある定数を更新すると、さまざまなシート、スプレッドシート、レポート、アプリ、PES指標でスクリプトを使用できるようになります。
- const SPREADSHEET_ID_PES = "ENTER-YOUR-SPREADSHEET-ID"で、ENTER-YOUR-SPREADSHEET-IDの部分をスプレッドシートのIDに置き換えます。この値を取得するには、次のURLのIDをコピーします：https://docs.google.com/spreadsheets/d/ここにスプレッドシートのIDを挿入/edit#gid=0
- const SHEET_NAME_PES = "ENTER-YOUR-SPREADSHEET-TAB"で、ENTER-YOUR-SPREADSHEET-TABの部分をシートタブの名前に置き換えます。
- const INTEGRATION_KEY_PES = "YOUR-INTEGRATION-KEY"で、YOUR-INTEGRATION-KEYの部分を、サポートされているインテグレーションキーに置き換えます。Pendoのインテグレーションキーで説明しているとおり、インテグレーションキーはPendoの管理者しか作成できません。Pendoからのデータ抽出については、閲覧者のアクセス権があれば実施できます。
- const APP_ID = ENTER-YOUR-APP-IDで、ENTER-YOUR-APP-IDの部分を、データの抽出元となるPendoアプリケーションのIDに置き換えます。Pendoサブスクリプションにウェブアプリケーションが1つしかない場合、IDは-323232となります。これを変更する必要はありません。サブスクリプションにアプリケーションが複数ある場合は、マルチアプリAPIの資料を参照して、この値を取得方法を確認してください。
-
Const BASE_URL = "app.pendo.io"の場合、これがPendoへのアクセスに使用するURLであることを確認してください。
- USインスタンス（app.pendo.io）経由でPendoにアクセスした場合、 デフォルトですでに正しい値が入力されているため、アクションは一切必要ありません。
- PendoサブスクリプションがEUインスタンスにある場合は、app.pendo.ioをapp.eu.pendo.ioに変更します。
- PendoサブスクリプションがJPNインスタンスにある場合は、app.pendo.ioをapp.jpn.pendo.ioに変更します。
- PendoサブスクリプションがUS1インスタンスにある場合は、app.pendo.ioをapp.us1.pendo.ioに変更します。
- const NUMBER_OF_DAYS = ENTER-NUMBER-OF-DAYSで、分析する日数を入力します。たとえば、過去180日間の分析を実施するには、180と入力します。
-
以下の残りの定数については、Pendoの［行動］>［PES］>［PESを管理］にあるPESの設定に基づいて、引用符内の値を更新します。
const ADOPTION_USERBASE ="visitors";
const STICKINESS_USERBASE ="visitors";
const STICKINESS_NUMERATOR ="weekly" ;
const STICKINESS_DENOMINATOR ="monthly";
const STICKINESS_EXCLUDE_WEEKENDS ="true";
const GROWTH_USERBASE ="visitors";
- const SPREADSHEET_ID_PES = "ENTER-YOUR-SPREADSHEET-ID"で、ENTER-YOUR-SPREADSHEET-IDの部分をスプレッドシートのIDに置き換えます。この値を取得するには、次のURLのIDをコピーします：https://docs.google.com/spreadsheets/d/ここにスプレッドシートのIDを挿入/edit#gid=0
-
保存アイコンを選択し、［実行（Run）］を選択します。これにより、スクリプト内のデータへのGoogleアクセスを承認するためのダイアログが開きます。
- ［権限を確認（Review permissions）］を選択し、お使いのGoogleアカウントを選び、［許可（Allow）］を選択します。
- Googleスプレッドシートがレポートの情報で更新され、Pendoのレポートと同じ内容が表示されていることを確認します。
ボタンを使用したレポート内容の更新
必要に応じて、スプレッドシートにボタンを追加すれば、そのボタンを選択するたびにコードが実行され、最新のレポートの内容でスプレッドシートが更新されるようになります。
- Googleスプレッドシートで、［挿入］>［図形描画］の順に選択します。
- 図形を選択し、好みの形に整えてから、［保存して終了］を選択します。
- スプレッドシートに図形を追加したら、その図形を右クリックして右上に表示される省略記号（3つの点）を選択し、［スクリプトを割り当て］を選びます。
- MainPES（コードに含まれる関数の名前）と入力し、［確定］を選択します。
- ボタンを選択して、期待どおりにデータが更新されることを確認します。
スケジュールに沿ったレポート内容の更新
Pendoのレポート内容を定期的に抽出するように自動プロセスを設定することもできます。
- Googleスプレッドシートで、［拡張機能］>［Apps Script］の順に選択します。
- 左のナビゲーションメニューから、［トリガー］（時計のアイコン）を選択します。
- ページの右下にある［トリガーを追加］を選択します。
- ニーズに合わせてトリガーを設定します。各フィールドの説明は以下のとおりです。
- 実行する機能を選択：これにより、前のセクションのステップ4でコードに追加されたgetReport関数が自動的に検出されます。この選択は変更しないでください。
- 実行するデプロイを選択：このオプションはデフォルトで［Head］が選択されています。この選択は変更しないでください。
- イベントのソースを選択：ドロップダウンメニューから［時間主導型］を選択します。これにより、次の2つのドロップダウンオプションが更新されます。
- 時間ベースのトリガーのタイプを選択：レポートを毎日更新したい場合は、［日付ベースのタイマー］を選択します。
- 時刻を選択：ニーズに最も適した時刻を選択します。ユーザーのタイムゾーンが自動的に検出されます。
-
エラー通知設定：［今すぐ通知を受け取る］を選択することをお勧めしますが、選択肢は他にもあります。フィールド名の横にあるプラス（+）アイコンを選択すると、複数選択が可能になります。
- ［保存］を選択すると、スケジュールされた時刻にスクリプトを実行するトリガーが追加されます。