Things Cloud Web SDK アプリケーション構成

アプリケーション構成

Web SDK で作成されたすべてのアプリケーションは、カスタムビルドを通じて完全にカスタマイズ可能です。アプリケーションを構築せずにブランディングと構成オプションを活用することをお勧めします。これにより、この構成を複数のアプリケーション間で共有できるようになります。このセクションでは、まず「ビルドなしのオプション」について概説し、その後、構築されたアプリケーションをカスタマイズする方法を詳しく説明します。

アプリケーションオプション

アプリケーションをカスタマイズする最も簡単なオプションは、アプリケーションオプションです。これはすべての Web SDK アプリケーションに適用され、継承を使用することで、すべてのアプリケーションに同じ構成を適用できます。設定の一例としては、hideNavigator があります。これは、アプリケーションの起動時にナビゲータを表示するかどうかを構成するシンプルなフラグです。これは 3 つの方法で構成できます。

URL パラメータ
動的パブリックオプション
静的プライベートオプション

継承に関しては、「URL パラメータ」オプションが最も高い権限を持ち、次に「動的パブリックオプション」と「静的プライベートオプション」が続きます。特定のオプションをテストするには、アプリケーションに URL パラメータを追加するだけです。例えば、ナビゲータを非表示にするには、URL apps/<<your-app-name>>/index.html?hideNavigator=true#/route を使用します。URL パラメータは、#ハッシュナビゲーションの前に設定する必要があります。

動的なパブリックオプションは、各 Web SDKベースのアプリケーションの起動時にリクエストされます。このオプションのデフォルトの取得 URL は dynamicOptionsUrl に保存され、デフォルトでは "/apps/public/public-options/options.json" に設定されています。コンテキストパスからわかるように、デフォルト設定はテナントにデプロイされたアプリケーションを指しています。このアプリケーションを独自に作成するには、public-options.zip という zip ファイルを作成し、options.json を追加します。

{
  hideNavigator: true
}

このアプリケーションをテナントにアップロードし、少なくとも 1 つのサブテナントに登録すると、すべての Web SDK ベースのアプリケーションはナビゲータがデフォルトで非表示になります。

備考

エンタープライズテナント（親テナント）のお客様の場合、このオプションを操作する最も簡単な方法は、管理のブランディングマネージャーを使用することです。これにより、JSON ファイルを手動で生成してアプリケーションをアップロードすることなく、ほとんどの設定を行うことができます。

静的プライベートオプションは、カスタムアプリケーションによってのみ定義できます。これは最下位レベルのオプションであり、上位のオプション (1 および 2) によって上書きできます。これらはプライベートであり、適用されている現在のアプリケーションにのみ適用されます。これらのオプションは、cumulocity.config.ts ファイルの runTime フラグメントに追加することで定義できます。

[...]
export default {
  runTime: {
    [...]
    hideNavigator: true
  },
}
[...]

cumulocity.config.ts ファイル内のオプションは、環境変数にアクセスすることでビルド時に動的に設定することもできます。

[...]
export default {
  runTime: {
    [...]
    hideNavigator: process.env.C8Y_HIDE_NAVIGATOR === 'true'
  },
}
[...]

環境変数 C8Y_HIDE_NAVIGATOR を true に設定してから ng build を介してアプリケーションをビルドすると、アプリケーションの動作を調整できます。Linux システムでは、次のように環境オプションを設定してビルドコマンドを実行できます。

C8Y_HIDE_NAVIGATOR=true ng build

例えば、アプリケーションに複数の「フレーバー」がある場合、cumulocity.config.ts 内の環境変数を使用して、異なるフレーバーを切り替えることもできます。

const flavor = process.env.C8Y_APP_FLAVOR || 'default';
let standardOptions: ConfigurationOptions = {
  runTime: {
    // [...]
    rightDrawer: true,
  },
  buildTime: {
    // [...]
  }
};

switch (flavor) {
  case 'customerA':
    standardOptions.runTime.hideNavigator = true;
    break;

  case 'customerB':
    standardOptions.runTime.hideNavigator = false;
    break;
}

export default standardOptions;

フレーバー固有のブランディングを行うには、angular.json で異なるブランディングファイルを指定します。

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "configurations": {
            "customerA": {
              "styles": [
                "src/branding/branding-customerA.less"
              ]
            },
            "customerB": {
              "styles": [
                "src/branding/branding-customerB.less"
              ]
            }
          }
        }
      }
    }
  }
}

次のコマンドで、さまざまなフレーバーをビルドできます。

ng build --configuration=customerA

オプションの動作を確認するには URL オプションを使用するか、または、プラットフォーム全体（ブランディング）でオプションを設定するには動的オプションを使用し、カスタムアプリケーションのデフォルトを設定するにはプライベート静的オプションを使用することをお勧めします。

利用可能なすべてのオプションを確認するには、Things Cloud Codex のアプリケーションオプションによるスタイル設定を参照してください。

アプリケーションのブランディング

ブランディングは、すべてのアプリケーションに必ず適用する必要があります。そのため、アプリケーションのブランディングには、動的なパブリックオプションを使用することをお勧めします。 brandingCssVars アプリケーションオプションに適切なデザイントークンを設定する必要があります。これらは、Things Cloud のすべてのデフォルトスタイルシートに適用される CSS 変数であり、あらゆる Web SDK アプリケーションにカスタムブランディングを表示します。 options.json は次のようになります。

{
  "brandingCssVars": {
    "--brand-primary": "#B10F2E",
    "--brand-complementary": "#DE7C5A",
    "--brand-dark": "#280000",
    "--brand-light": "#DE7C5A",
    "--palette-status-realtime" : "#f0f"
  }
}

hideNavigator などの他のオプションを追加したり、独自の CSS ファイルを追加したりすることもできます。

{
  "brandingCssVars": {
    "--brand-primary": "#B10F2E",
    "--brand-complementary": "#DE7C5A",
    "--brand-dark": "#280000",
    "--brand-light": "#DE7C5A",
    "--palette-status-realtime" : "#f0f"
  },
  "hideNavigator": true,
  "extraCssUrls": "./custom.css",
}

CSS ファイルには、独自のスタイルを追加できます。

h1 {
  color: #00f;
}

次の手順に従ってください。

ファイルを zip ファイルに圧縮し、ラッピングフォルダなしで zip のルートに配置します。
zip ファイル名を public-options.zip にします。
管理 > エコシステム > アプリケーション で、Web アプリケーションとしてアップロードします。
テナント > サブテナント で、アプリケーションをいずれかのテナントに登録します。

その後、アプリケーションの詳細ビューで新しい変数を使用して既存のアプリケーションを更新できます。

備考

エンタープライズテナント（親テナント）のお客様の場合、このオプションを操作する最も簡単な方法は、管理のブランディングマネージャーを使用することです。このフォームでは、JSON ファイルを手動で生成したりアプリケーションをアップロードしたりすることなく、ほとんどの設定を行うことができます。

@c8y/style の拡張によるスタイル設定

アプリケーションのスタイルには、LESS で作成されたグローバル CSS が使用されています。元の LESS ソースは npm パッケージの @c8y/style で配布されています。既存のスタイルを拡張することによって、アプリケーション設定の詳細まで変更できますが、多くの開発者は色やロゴ、フォントなど数個の変数を置き換えるだけで簡単に実現したいと思っているでしょう。

重要

推奨アプローチ: ほとんどのユースケースでは、管理アプリケーションの ブランディングエディター を CSS 変数（以下のアプローチ 1）とともに使用することを推奨します。これにより、アプリケーションをリビルドせずに実行時のカスタマイズが可能になり、開発者以外のユーザーにも使いやすいインターフェースが提供されます。

LESS 変数（アプローチ 2）は、ビルド時のカスタマイズが必要な高度なシナリオ、またはブランディングエディターが提供する範囲を超えてスタイルをより深く制御する必要がある場合にのみ使用してください。

変数を上書きするには、Custom CSS Properties（CSS Variables とも呼ばれます）を利用できます。これにより、実行時またはビルドプロセス中に構成が可能になります。

セットアップ手順

プロジェクトが Angular CLI に基づいていることを確認してください（アップグレード版でも、最初から作成したものでも構いません）。
@c8y/style パッケージがインストールされていることを確認してください。インストールされていない場合は、次のコマンドを使用して npm から基本スタイルをインストールできます。
```
npm install @c8y/style
```
この例では、次のファイル構造を使用しています。
```
my-application
|   ...
│   angular.json
│   package.json
|   ...
└───src
    │   styles.less
    │   favicon.ico
    │   ...
    └─── assets
         │   logo.jpg
         │   ...
```
styles.less がすでに存在する場合、ファイルの先頭に @import '~@c8y/style/extend.less'; の行を追加します。存在しない場合は、作成して上記の行を追加します。

/* src/styles.less */
@import '~@c8y/style/extend.less';

プロジェクトエントリの下にある angular.json の styles エントリに styles.less ファイルを含めます。

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "src/styles.less"
            ]
          }
        }
      }
    }
  }
}

重要

インポート順序は重要です: 必ずファイルの先頭で @c8y/style/extend.less を 最初に インポートし、その後に変数を上書きしてください。これにより、条件付きガードシステムが上書きを正しく検出できるようになります。

カスタマイズ例

現時点では、必要に応じて好きな変数を変更することが可能です。これらの変更を実装するには、次の例に従い、指定されたコードを styles.less ファイルに追加してください。

アプローチ 1: CSS 変数を使用（実行時）— 推奨

CSS 変数を直接設定できるため、実行時のカスタマイズが可能です。

利点:

✅ リビルドや再デプロイが不要
✅ 変更が実行時に即時反映
✅ ブランディングエディター UI で管理可能
✅ テナント全体で全アプリケーションに適用
✅ 開発者以外にも扱いやすい

  /* src/styles.less */
  @import '~@c8y/style/extend.less';

  :root {
    --brand-primary: red;
    --brand-logo-img: url('/apps/<applicationContextPath>/assets/logo.jpg');
    --brand-logo-img-height: 48%;
  }

applicationContextPath には、プラットフォームにアップロードした logo.jpg ファイルを含む任意のアプリケーションを指定できます。

ボタン、有効になっているナビゲーションノード、有効になっているタブなどのユーザーインターフェース要素には、カスタムのブランドカラーが使用されます。

アプローチ 2: LESS 変数を使用（ビルド時）— 高度

高度なビルド時カスタマイズのシナリオでは、extend.less をインポートした後に LESS 変数を上書きします。

使用する場面:

CSS 変数を超える高度なスタイル要件
スタイルをビルド時に組み込む必要がある場合
特定のスタイル要件を持つカスタムアプリケーション

注記: 変更を反映するには、アプリケーションのリビルドと再デプロイが必要です。

/* src/styles.less */
/* 1. Import Cumulocity styles FIRST */
@import '~@c8y/style/extend.less';

/* 2. Override LESS variables AFTER with direct values */
@brand-primary: #e30613;  /* Your custom brand color (must use direct hex value) */

/* 3. Logo configuration (paths relative to your styles.less file) */
@brand-logo-img-fallback: '../assets/logo.jpg';
@brand-logo-height-fallback: 48%;

/* 4. Navigator logo */
@navigator-platform-logo-fallback: '../assets/logo-white.png';
@navigator-platform-logo-height-fallback: 28%;

/* Apply navigator logo (required for extend.less pattern) */
.navigator .tenant-brand {
  background-image: var(--c8y-navigator-platform-logo);
  padding-bottom: var(--c8y-navigator-platform-logo-height);
}

重要

LESS 変数に関する重要ルール:

常に直接の色値（例: #e30613）を使用してください（@my-color ではありません）。
変数を上書きする前に extend.less をインポートしてください。
ロゴのパスは styles.less ファイルの場所からの相対パスです。
LESS 変数を使用する場合、ナビゲータロゴのために明示的な CSS ルールを追加してください。

言語のカスタマイズ

言語の国際化に使用されているプラットフォーム UI 文字列は、gettext に保存されています。プラットフォームに新しい言語を追加したい場合、これらのファイルを編集するソフトウェアが必要です（Poedit など）。

翻訳されている各カタログは JSON 形式で実行時に読み込まれます。.po（gettext）拡張子のファイルを .json ファイルに変換するには、最初の手順でインストールした @angular/cli を使用します。

ビルド時に独自翻訳の追加方法

@c8y/ngx-components@1004.0.6/locales/locales.pot から文字列カタログをダウンロードします（バージョン1004.0.6以降では、latest を現在使用しているバージョンに変更することができます）。
ダウンロードした locales.pot テンプレートファイルを、任意の .pot ファイルエディタにロードし、そこから新しい翻訳を作成します。翻訳対象言語（Afrikaansなど）を選択し、各文字列を翻訳します。必要な数の言語について、このプロセスを繰り返します。この手順の成果物として、各言語の .po カタログファイルができ上がります。これらのファイルは後続のバージョンで文字列を更新するときに使うため、安全な場所に保存しておいてください。
c8ycli を利用して、新しく作成された .po ファイルを .json ファイルへ変換します。

c8ycli locale-compile path/to/language.po

ui-assets フォルダへ生成された .json ファイルをコピーします。
public-options/options.json の language フラグメントを更新します。

languages?: {
  [langCode: string]: {
    name: string;
    nativeName: string;
    url: string;
  }
}

リポジトリにダウンロード可能なサンプルコードでは、次のようなウクライナ語への翻訳例があります。

[...]

export default {
  runTime: {
    [...]
    languages: {
      uk: {
        name: "Ukraine",
        nativeName: "українська",
        url: "/apps/public/ui-assets/uk.json"
      }
    }
  },
  buildTime: {
    [...]
  }
}
[...]

ログイン後、UI でインポートした言語を変更できます。これを行うには、右上のユーザーアイコンをクリックし、メニューから「ユーザー設定」を選択して、表示されるウィンドウで目的の言語を選択します。

実行時に独自翻訳の追加方法

特定の文字列を実行時に翻訳することができます。つまり、ビルドに含める必要はなく、単にアプリケーションオプションに追加するだけです。しかし、この考え方では、新しい言語を追加することはできません。新しい文字列を既存の言語に追加するか、特定の翻訳を既存の言語に揃えることしかできません。特定キーを翻訳するためには、アプリケーションオプションに次の構造を追加する必要があります。

  i18nExtra?: {
    [langCode: string]: {
      [key: string]: string;
    };
  };

例：
次のようにすると、独自のCookieバナーが翻訳されます。

[...]

export default {
  runTime: {
    [...]
    i18nExtra: {
      de: {
        "About cookies on Things Cloud": "Informationen zu Cookies in Things Cloud",
        "Click Agree and Proceed to accept cookies and go directly to the platform or click on Privacy Policy to see detailed descriptions of the used cookies.": "Klicken Sie auf Zustimmen und fortfahren, um Cookies zu akzeptieren und direkt zur Plattform zu gelangen, oder klicken Sie auf Datenschutzrichtlinie, um detaillierte Beschreibungen der verwendeten Cookies anzuzeigen."
      }
    }
  },
  buildTime: {
    [...]
  }
}
[...]