構成ページを作成する

構成ページは、特別な種類の コンテンツ ページです。 ユーザーは、構成ページを使用して Microsoft Teams アプリのいくつかの側面を構成し、その構成を次の一部として使用します。

注意

このトピックでは、Microsoft Teams JavaScript クライアント SDK のバージョン 2.0.0 を反映しています。 以前のバージョンを使用している場合は、v1 と v2 の違いに関するガイダンスについては、Teams JS SDK の概要を参照してください。

チャネルまたはグループチャット タブを構成する

アプリケーションは、 Microsoft Teams JavaScript クライアントSDK を参照し、app.initialize() を呼び出す必要があります。 使用される URL は、セキュリティで保護された HTTPS エンドポイントであり、クラウドから使用できる必要があります。

構成ページの例を次の図に示します。

Configuration page

次のコードは、構成ページに対応するコードの例です。

<head>
    <script src='https://statics.teams.cdn.office.net/sdk/v2.0.0/js/MicrosoftTeams.min.js'></script>
</head>
<body>
    <button onclick="(document.getElementById('icon').src = '/images/iconGray.png'); colorClickGray()">Select Gray</button>
    <img id="icon" src="/images/teamsIcon.png" alt="icon" style="width:100px" />
    <button onclick="(document.getElementById('icon').src = '/images/iconRed.png'); colorClickRed()">Select Red</button>

    <script>
        app.initialize();
        let saveGray = () => {
            pages.config.registerOnSaveHandler((saveEvent) => {
                const configPromise = pages.config.setConfig({
                    websiteUrl: "https://yourWebsite.com",
                    contentUrl: "https://yourWebsite.com/gray",
                    entityId: "grayIconTab",
                    suggestedDisplayName: "MyNewTab"
                });
                configPromise.
                    then((result) => {saveEvent.notifySuccess()}).
                    catch((error) => {saveEvent.notifyFailure("failure message")});
            });
        }

        let saveRed = () => {
            pages.config.registerOnSaveHandler((saveEvent) => {
                const configPromise = pages.config.setConfig({
                    websiteUrl: "https://yourWebsite.com",
                    contentUrl: "https://yourWebsite.com/red",
                    entityId: "redIconTab",
                    suggestedDisplayName: "MyNewTab"
                });
                configPromise.
                    then((result) => {saveEvent.notifySuccess();}).
                    catch((error) => {saveEvent.notifyFailure("failure message")});
            });
        }

        let gr = document.getElementById("gray").style;
        let rd = document.getElementById("red").style;

        const colorClickGray = () => {
            gr.display = "block";
            rd.display = "none";
            pages.config.setValidityState(true);
            saveGray()
        }

        const colorClickRed = () => {
            rd.display = "block";
            gr.display = "none";
            pages.config.setValidityState(true);
            saveRed();
        }
    </script>
    ...
</body>

タブのコンテンツを灰色または赤色のアイコンで表示するには、構成ページで [灰色を選択] または [赤色を選択] ボタンを選択します。

次の図は、[灰色] のアイコンが選択されたタブコンテンツを表示します。

Configure tab with select gray

次の図は、[赤] のアイコンが選択されたタブコンテンツを表示します。

Configure tab with select red

適切なボタンを選択すると、saveGray() または saveRed() のいずれかがトリガーされ、以下が呼び出されます。

  • pages.config.setValidityState(true) を true に設定します。
  • pages.config.registerOnSaveHandler()イベント ハンドラーがトリガーされます。
  • アプリの構成ページで [保存] が有効になっています。

構成ページ コードは、構成要件が満たされ、インストールを続行できることを Teams に通知します。 ユーザーが [保存] を選択すると、Config インターフェースで定義されているように pages.config.setConfig() のパラメーターが設定されます。 詳細については、「 構成インターフェイス」を参照してください。 saveEvent.notifySuccess() は、コンテンツ URL が正常に解決されたことを示すために呼び出されます。

注意

  • タイムアウトまでに保存操作 (registerOnSaveHandler へのコールバック) を完了するまでに 30 秒かかります。 タイムアウト後、一般的なエラー メッセージが表示されます。
  • registerOnSaveHandler() を使用して保存ハンドラーを登録する場合、コールバックは saveEvent.notifySuccess() または saveEvent.notifyFailure() を呼び出して、構成の結果を示す必要があります。
  • 保存ハンドラーを登録しない場合、ユーザーが [保存] を選択すると、saveEvent.notifySuccess() 呼び出しが自動的に行われます。

タブのコンテキストを取得する

お使いのタブでは、関連するコンテンツを表示するためにコンテキスト情報が必要になる場合があります。 コンテキスト情報は、よりカスタマイズされたユーザー エクスペリエンスを提供することで、タブの魅力をさらに高めます。

タブ構成に使用されるプロパティの詳細については、 コンテキスト インターフェイスを参照してください。 コンテキスト データ変数の値を次の 2 つの方法で収集します。

  • マニフェストの configurationURL に URL クエリ文字列プレースホルダーを挿入します。

  • Teams SDK app.getContext() メソッドを使用します。

configurationUrl にプレースホルダーを挿入します。

ベース configurationUrl にコンテキスト インターフェイス プレースホルダーを追加します。 次に例を示します。

ベース URL
...
"configurationUrl": "https://yourWebsite/config",
...

クエリ文字列を含むベース URL

...
"configurationUrl": "https://yourWebsite/config?team={teamId}&channel={channelId}&{locale}"
...

ページのアップロード後、Teams クエリ文字列プレースホルダーが関連する値で更新されます。 これらの値を取得して使用するには、構成ページにロジックを含めます。 URL クエリ文字列の操作の詳細については、MDN Web Docs の URLSearchParams を参照してください。 次のコード例は、configurationUrl プロパティから値を抽出する方法を示しています。

<script>
   app.initialize();
   const getId = () => {
        let urlParams = new URLSearchParams(document.location.search.substring(1));
        let blueTeamId = urlParams.get('team');
        return blueTeamId
    }
//For testing, you can invoke the following to view the pertinent value:
document.write(getId());
</script>

関数を getContext() 使用してコンテキストを取得する

この関数は app.getContext()コンテキスト インターフェイス オブジェクトを使用して解決する Promise を返します。

次のコードは、この関数を構成ページに追加してコンテキスト値を取得する例を示しています。

<!-- `userPrincipalName` will render in the span with the id "user". -->

<span id="user"></span>
...
<script>
    const contextPromise = app.getContext();
    contextPromise.
        then((context) => {
            let userId = document.getElementById('user');
            userId.innerHTML = context.user.userPrincipalName;
        }).
        catch((error) => {/*Unsuccessful operation*/});
</script>
...

コンテキストと認証

ユーザーにアプリの構成を許可する前に認証します。 そうしないと、コンテンツに認証プロトコルを持つソースが含まれる可能性があります。 詳細については、「Microsoft Teams タブでユーザーを認証する」を参照してください。コンテキスト情報を使用して、認証要求と承認ページ URL を作成します。 タブ ページで使用されているすべてのドメインが manifest.json および validDomains 配列にリストされていることを確認してください。

タブを変更または削除する

マニフェストの canUpdateConfiguration プロパティ trueを . これにより、ユーザーはチャネルまたはグループ タブを変更、再構成、または名前変更できます。タブが削除されたときのコンテンツへの影響についてユーザーに通知します。 これを行うには、アプリに [削除オプション] ページを含め、(以前の) 構成でプロパティのsetConfig()removeUrlsetSettings()設定します。 ユーザーは個人用タブをアンインストールできますが、変更することはできません。 詳細については、「タブの削除ページを作成する」を参照してください。

setConfig() 削除ページのMicrosoft Teams (以前setSettings()の) 構成:

const configPromise = pages.config.setConfig({
    contentUrl: "add content page URL here",
    entityId: "add a unique identifier here",
    suggestedDisplayName: "add name to display on tab here",
    websiteUrl: "add website URL here //Required field for configurable tabs on Mobile Clients",
    removeUrl: "add removal page URL here"
});
configPromise.
    then((result) => {/*Successful operation*/).
    catch((error) => {/*Unsuccessful operation*/});

モバイル クライアント

Teams モバイル クライアントに、チャネルまたはグループ タブを表示するように選択した場合は、setConfig()の構成にはwebsiteUrlの値を設定する必要があります。 詳細については、「モバイル上のタブに関するガイダンス」を参照してください。

次のステップ

関連項目