はじめに
kintoneのカスタマイズで、画面遷移用のURLを組み立てることはありませんか？
これまでだと、次のように URLを文字列結合 で組み立てることが多かったと思います。
window.location.href =
'会社のドメイン' + 'cybozu.com' + '/k/' + kintone.app.getId() + '/';
2025年11月版のkintoneから、kintone.buildPageUrl() で画面URLを公式APIから組み立てられるようになりました！
本記事では、画面遷移を buildPageUrl() に置き換えるメリット と、buildPageUrl() のユースケース を紹介します👍
buildPageUrl() とは
kintone.buildPageUrl(page, params) は、kintone内の画面URLを組み立てて返す 非同期API です。
page ：遷移先の画面種別を指定します。
params ：画面ごとに必要なID（appId など）を指定します。
このAPIでは指定できるpageとparamsが非常に多いので、この記事では割愛させていただきます。
詳しく読みたい方、公式ドキュメントは次のとおりです。
buildPageUrl() は 非同期API です。
async / await を使ってください。
buildPageUrl()を使うメリット
このようにURLを文字列結合で組み立てる書き方は一見シンプルですが...
window.location.href =
'会社のドメイン' + 'cybozu.com' + '/k/' + kintone.app.getId() + '/';
実は色々不便なところが出てくる😢
そのため、buildPageUrl()に置き換えるとたくさんのメリットがあります！
今回はいくつかを紹介します👏
kintoneのアップデートでURL形式が変わる場合に備えられる
1つ目は、kintoneのアップデートでURL形式が変わったときに、カスタマイズを動かなくなるリスクがあります。
会社名の変更により、「サブドメイン」の変更が発生する可能性があります
https://jp.kintone.help/general/ja/id/02076
文字列結合でURLを組み立てている場合、すべてのカスタマイズに入っているURLを書き換える必要があります。
この場合、多数のカスタマイズで広い範囲の変更が必要になります...
buildPageUrl() は、そのような変更に備えやすくなります！
ゲストスペース用のURLが自動的に組み立てられる
2つ目は、遷移先がゲストスペース内アプリの場合、ゲストスペース用のURLが自動的に組み立てられることです。
ゲストスペースのURLは、通常のスペースのURLとは異なります（/k/ の後ろに guest/ が入ります）。
文字列結合でURLを組み立てている場合、毎回遷移先がゲストスペースかどうかを判定する分岐処理が必要です。
buildPageUrl() を使えば、その分のコードを省略できます！
多様なURLを組み立てることが可能
3つ目は、アプリやスペース以外の画面URLも、buildPageUrl() で組み立てられることです。
文字列結合でURLを作るときは、/k/{アプリID}/ や /k/guest/{スペースID}/... といった アプリ・スペース向けのパターン を覚えていれば足りることが多いです。
一方で、kintone には次のような画面もあります。
アプリIDだけでは組み立てられず、文字列結合だと調査する必要があります。
- ピープルの画面
- メッセージの画面
- 検索の画面
- 通知の画面（PCのみ）
- アプリストアの画面（PCのみ）
ピープルやメッセージでは params.userCode の指定が必須です。
画面ごとに必要なパラメーターが異なるため、組み立てるときは公式
ドキュメント の一覧表を確認してください。
アプリ遷移が主役のカスタマイズでも、「担当者のプロフィールへ」「社内検索へ」といった導線を足したくなったときに、buildPageUrl() が活きてきます。
ユースケース
💻背景
🧑💼とある会社にイベント管理者がいました。
- 社外向けのコンテストイベントを開催しており、イベント用のゲストスペースを作っています
- ゲストスペースにある「イベント参加アプリ」に退席ボタンを押してもらうことで、誰がいつ退席したかを把握したい
- 退席後は、自分が対象となるアンケートアプリへそのまま遷移して回答してもらいたい
そのため、退席後にアンケートアプリへ直接遷移できる導線を作りたい、という場面です。
💻動作イメージ
コンテストイベントでは、「審査員」と「応募者」が両方参加しています。
「審査員」のアンケートアプリは自社ドメインに置きたく、「応募者」のアンケートアプリはゲストスペースに置きたいです。
イベント出席アプリでは、次の動作を想定しています。
- 各参加者の画面に「出席」「退席」ボタンを配置する
- 「出席」を押すと出席時刻が記録される
- 「退席」を押すと退席時刻が記録され、
buildPageUrl()で該当するアンケートアプリが自動で開く
💻サンプルコード
今回のデモとして使った「イベント出席アプリ」のフィールド構成は次のとおりです。
| フィールド名 | フィールドコード | 種類 |
|---|---|---|
| 区分 | category | ラジオボタン |
| 出席ボタン用スペース | checkin | スペース |
| 退席ボタン用スペース | checkout | スペース |
| 出席時刻 | checkinTime | 時刻 |
| 退席時刻 | checkoutTime | 時刻 |
レコード詳細画面では kintone.app.record.set() が使えないため、出席・退席時刻の更新は REST API（PUT）で行います。
退席ボタン押下後は、category の値に応じて buildPageUrl() でアンケートアプリの追加画面URLを取得し、画面遷移します。
/*
* Copyright (c) 2026 Cybozu
*
* Licensed under the MIT License
* https://opensource.org/license/mit/
*/
(() => {
'use strict';
// category の値ごとに、遷移先アンケートアプリの appId を定義
const SURVEY_APPS = {
応募者: { appId: '1' },
審査員: { appId: '2' },
};
// UTC から JST（+9時間）の時刻を HH:mm 形式で返す
const getCurrentTime = () => {
return new Date(Date.now() + 32400000).toISOString().slice(11, 16);
};
// 詳細画面では kintone.app.record.set() が使えないため、REST API で更新する
const updateField = async (fieldCode) => {
const body = {
app: kintone.app.getId(),
id: kintone.app.record.getId(),
record: {
[fieldCode]: { value: getCurrentTime() },
},
};
await kintone.api(kintone.api.url('/k/v1/record.json', true), 'PUT', body);
};
// category に応じたアンケートアプリの「レコード追加画面」URLを buildPageUrl() で取得
const getSurveyPageUrl = async (category) => {
const app = SURVEY_APPS[category];
const params = { appId: app.appId };
return kintone.buildPageUrl('APP_CREATE', params);
};
// 退席時刻を記録してから、アンケートアプリへ遷移
const redirect = async (category) => {
await updateField('checkoutTime');
const url = await getSurveyPageUrl(category);
window.location.href = url;
};
const createButton = (label, onClick) => {
const button = document.createElement('button');
button.textContent = label;
button.type = 'button';
button.onclick = onClick;
return button;
};
kintone.events.on('app.record.detail.show', (event) => {
// スペースフィールド（checkin / checkout）を取得
const checkinSpace = kintone.app.record.getSpaceElement('checkin');
const checkoutSpace = kintone.app.record.getSpaceElement('checkout');
// 退席後の遷移先を決めるため、category フィールドの値を取得
const category = event.record.category.value;
if (checkinSpace && checkinSpace.childElementCount === 0) {
checkinSpace.appendChild(
createButton('出席', async () => {
await updateField('checkinTime');
location.reload();
}),
);
}
if (checkoutSpace && checkoutSpace.childElementCount === 0) {
checkoutSpace.appendChild(createButton('退席', () => redirect(category)));
}
return event;
});
})();
退席ボタンを押すと、category に応じて次の画面へ遷移します。
審査員は自社ドメインのアンケートアプリ、応募者はゲストスペース内のアンケートアプリが開きます。
本来は分岐処理を書かなければいけないゲストスペースのURL作りは、これくらいコンパクトなコードで解決できました。
const getSurveyPageUrl = async (category) => {
const app = SURVEY_APPS[category];
const params = { appId: app.appId };
return kintone.buildPageUrl('APP_CREATE', params);
};
注意事項
buildPageUrl() を使う前に、次の点を確認してください。
-
利用できない画面がある
検索画面・アプリストア・プラグイン設定画面では、このAPIを呼び出せません。
遷移先として検索画面のURLを組み立てること自体は可能です。 -
呼び出し回数に上限がある
ユーザーごとに1分あたり50回を超えると、Promiseが拒否されます。
画面表示のたびに大量に呼ばないよう注意してください。 -
pageとparamsの組み合わせ
必須パラメーターが不足していると、URLは正しく組み立てられません。
公式ドキュメントの一覧表を都度確認することをおすすめします。
おわりに
本記事では、buildPageUrl() を使った画面遷移の実装を紹介しました。
- ドメイン変更など、URL形式の変化に備えやすい
- ゲストスペース用URLを、分岐処理なしで組み立てられる
- アプリ以外の様々な画面URLも、公式APIで取得できる
今回のユースケースでは、同じ処理でフィールドの値に応じて自社スペースとゲストスペースそれぞれのアンケートアプリへ遷移する例を通して、ゲストスペース対応の楽さを紹介しました。
使う場面が増えるほど、buildPageUrl() の便利さが実感できると思います！
今後は、ぜひ画面遷移を伴うカスタマイズでは、文字列結合より先に buildPageUrl() を検討してみてください〜
この記事は、2026年6月版kintoneで動作を確認しています。