はじめに

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が非常に多いので、この記事では割愛させていただきます。
詳しく読みたい方、公式ドキュメントは次のとおりです。

kintone.buildPageUrl()

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で動作を確認しています。

参考リンク