QuickSight 埋め込みダッシュボードおよびビジュアルのルックアンドフィールをカスタマイズする - Amazon QuickSight
用語と概念セットアップSDK メソッドインターフェイステーマを使用した埋め込みコンテンツの初期化テーマオーバーライドを使用した埋め込みコンテンツの初期化プリロードされたテーマを使用した埋め込みコンテンツの初期化

QuickSight 埋め込みダッシュボードおよびビジュアルのルックアンドフィールをカスタマイズする

Amazon QuickSight Embedding SDK (バージョン 2.5.0 以降) を使用して、埋め込まれた QuickSight ダッシュボードおよびビジュアルのテーマ設定を実行時に変更できます。実行時のテーマ設定を使用すると、Software as a Service (SaaS) アプリケーションと Amazon QuickSight 埋め込みアセットを簡単に統合できます。実行時のテーマ設定を使用すると、埋め込まれたコンテンツのテーマを、QuickSight アセットが埋め込まれている親アプリケーションのテーマと同期できます。実行時のテーマ設定を使用して、閲覧者のためにカスタマイズオプションを追加することもできます。テーマ設定の変更は、初期化時、または埋め込みダッシュボードやビジュアルの存続期間を通じて、埋め込みアセットに適用できます。

テーマの詳細については、「Amazon QuickSight でのテーマの使用」を参照してください。QuickSight Embedding SDK の使用に関する詳細は、GitHub の「amazon-quicksight-embedding-sdk」を参照してください。

前提条件

開始する前に、次の前提条件を満たしていることを確認してください。

  • QuickSight Embedding SDK バージョン 2.5.0 以降を使用している。

  • 使用するテーマにアクセスするための許可。QuickSight のテーマに許可を付与するには、UpdateThemePermissions API 呼び出しを実行するか、または QuickSight コンソールの分析エディタでテーマの横にある [共有] アイコンを使用します。

用語と概念

次の用語は、埋め込みの実行時のテーマ設定を使用する場合に役立ちます。

  • テーマ – コンテンツの表示方法を変更する複数の分析とダッシュボードに適用できる設定を集めたもの。

  • ThemeConfiguration – テーマのすべての表示プロパティを含む設定オブジェクト。

  • テーマオーバーライド– コンテンツの表示方法の一部または全部の側面をオーバーライドするためにアクティブなテーマに適用される ThemeConfiguration オブジェクト。

  • テーマ ARN – QuickSight テーマを識別する Amazon リソースネーム (ARN)。カスタムテーマ ARN の例を次に示します。

    arn:aws:quicksight:region:account-id:theme/theme-id

    QuickSight が提供するスターターテーマのテーマ ARN には、リージョンが含まれていません。スターターテーマ ARN の例を次に示します。

    arn:aws:quicksight::aws:theme/CLASSIC

セットアップ

実行時のテーマ設定の使用を開始するには、次の情報を準備してください。

  • 使用するテーマのテーマ ARN。既存のテーマを選択することも、新しいテーマを作成することもできます。QuickSight アカウント内のすべてのテーマとテーマ ARN のリストを取得するには、ListThemes API オペレーションを呼び出します。プリセットの QuickSight テーマについては、「QuickSight API で Amazon QuickSight 分析のデフォルトテーマを設定する」を参照してください。

  • 登録済みユーザーの埋め込みを使用している場合は、使用するテーマにそのユーザーがアクセスできることを確認してください。

    匿名ユーザー埋め込みを使用している場合は、テーマ ARN のリストを GenerateEmbedUrlForAnonymousUser API の AuthorizedResourceArns パラメータに渡します。匿名ユーザーには、AuthorizedResourceArns パラメータにリストされているすべてのテーマへのアクセス権が付与されます。

SDK メソッドインターフェイス

設定メソッド

次の表には、デベロッパーが実行時のテーマ設定に使用できるさまざまなセッターメソッドの説明が記載されています。

メソッド 説明

setTheme(themeArn: string)

ダッシュボードまたはビジュアルのアクティブなテーマを別のテーマに置き換えます。適用すると、テーマのオーバーライドが削除されます。

テーマにアクセスできない場合、またはテーマが存在しない場合は、エラーが返されます。

setThemeOverride(themeOverride: ThemeConfiguration)

現在アクティブなテーマをオーバーライドするために動的な ThemeConfiguration を設定します。これは、以前に設定されたテーマのオーバーライドを置き換えます。新しい ThemeConfiguration で指定されていない値は、現在アクティブなテーマの値にデフォルトで設定されます。

指定した ThemeConfiguration が無効な場合は、エラーが返されます。

テーマを使用した埋め込みコンテンツの初期化

埋め込みダッシュボードまたはビジュアルをデフォルト以外のテーマを使用して初期化するには、DashboardContentOptions または VisualContentOptions パラメータで themeOptions オブジェクトを定義し、themeOptions 内の themeArn プロパティを目的のテーマ ARN に設定します。

次の例では、MIDNIGHT テーマを使用して埋め込みダッシュボードを初期化します。

import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        themeArn: "arn:aws:quicksight::aws:theme/MIDNIGHT"
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);

テーマオーバーライドを使用した埋め込みコンテンツの初期化

デベロッパーは、テーマオーバーライドを使用して、実行時に埋め込みダッシュボードまたはビジュアルのテーマを定義できます。これにより、QuickSight 内でテーマを事前に設定しなくても、ダッシュボードまたはビジュアルはサードパーティーアプリケーションからテーマを継承できます。埋め込みダッシュボードまたはビジュアルをテーマオーバーライドで初期化するには、 DashboardContentOptions または VisualContentOptions パラメータのいずれかの themeOptions 内の themeOverride プロパティを設定します。次の例では、ダッシュボードのテーマのフォントをデフォルトのフォントから Amazon Ember にオーバーライドします。

import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        "themeOverride":{"Typography":{"FontFamilies":[{"FontFamily":"Comic Neue"}]}}
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);

プリロードされたテーマを使用した埋め込みコンテンツの初期化

デベロッパーは、初期化時にプリロードされる一連のダッシュボードテーマを設定できます。これは、ダークモードやライトモードなど、さまざまなビューをすばやく切り替えるのに最も役立ちます。埋め込みダッシュボードまたはビジュアルは、最大 5 つのプリロードされたテーマで初期化できます。プリロードされたテーマを使用するには、最大 5 つの themeArns で配列内の DashboardContentOptions または VisualContentOptions の preloadThemes プロパティを設定します。次の例では、 Midnight と Rainier のスターターテーマをダッシュボードにプリロードします。

import { createEmbeddingContext } from 'amazon-quicksight-embedding-sdk';

const embeddingContext = await createEmbeddingContext();

const {
    embedDashboard,
} = embeddingContext;

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#experience-container',
};
const contentOptions = {
    themeOptions: {
        "preloadThemes": ["arn:aws:quicksight::aws:theme/RAINIER", "arn:aws:quicksight::aws:theme/MIDNIGHT"]
    }
};

// Embedding a dashboard experience
const embeddedDashboardExperience = await embedDashboard(frameOptions, contentOptions);