Extend App UI SDK API リファレンス

Last updated on July 14, 2026

注釈：本資料はAI技術を用いて翻訳されています。

Overview​

注記

公式の Extend App UI テンプレートを使用してプロジェクトをスキャフォールドした場合、このパッケージは既に含まれています。手動でインストールする必要はありません。

@accelbyte/sdk-extend-app-ui パッケージは、AccelByte Gaming Services（AGS）Admin Portal 内に組み込まれるマイクロフロントエンドである Extend App UI を構築するための公式 Extend App UI SDK です。以下を提供します。

  • 認証とパーミッションチェックを処理する React コンテキスト。
  • AGS バックエンドへのリクエストをプロキシする Vite 開発プラグイン。
  • ホスト（Admin Portal）とアプリ間のモジュールコントラクトのための TypeScript 型。

ここで説明されている内容を超える完全な TypeScript ソースと型定義については、npm 上の @accelbyte/sdk-extend-app-ui パッケージを参照してください。

Key terms​

共通の用語（Namespace、IAM パーミッション、AGS Public Cloud、AGS Private Cloud、App UI 名）については、Extend App UI の主要用語を参照してください。

  • マイクロフロントエンド: より大きなポータル内に組み込まれる、小規模で自己完結型の Web アプリケーション。Extend App UI は、AGS Admin Portal 内でネイティブのように動作するページとして実行されるマイクロフロントエンドです。

  • CORS: Web ページが、それを提供しているドメインとは異なるドメインへ直接 API リクエストを行うことをブロックするブラウザのセキュリティポリシーです。devProxyPlugin は、ローカル開発中にリクエストをローカル開発サーバー経由でルーティングすることで、これを回避します。

AppUIModule​

AppUIModule は、アプリがエクスポートする必要があるエントリポイントのコントラクトです。Admin Portal は、ユーザーが App UI を開いたときに mount(container, context) を呼び出し、ユーザーが移動したときに、それが返すクリーンアップ関数を呼び出します。

最小構成の例:

// module.tsx
import { type AppUIModule } from '@accelbyte/sdk-extend-app-ui'
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'

export const module: AppUIModule = {
  mount(container) {
    const root = createRoot(container)

    root.render(
      <StrictMode>
        <div>Hello world!</div>
      </StrictMode>
    )

    return () => root.unmount()
  }
}

完全な例（AGS SDK とパーミッションチェックを含む）:

AGS API 呼び出しやパーミッションチェックを行うには、AppUIContextProvider と QueryClientProvider でアプリをラップします。この SDK は内部で React Query を使用しているため、QueryClient が必要です。

// module.tsx
import { AppUIContextProvider, CrudType, useAppUIContext, type AppUIModule } from '@accelbyte/sdk-extend-app-ui'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'

const client = new QueryClient({ defaultOptions: { queries: { retry: false, refetchOnWindowFocus: false } } })

export const module: AppUIModule = {
  mount(container, hostContext) {
    const root = createRoot(container)

    root.render(
      <StrictMode>
        <QueryClientProvider client={client}>
          <AppUIContextProvider sdkConfig={hostContext.sdkConfig} isCurrentUserHasPermission={hostContext.isCurrentUserHasPermission}>
            <Component />
          </AppUIContextProvider>
        </QueryClientProvider>
      </StrictMode>
    )

    return () => root.unmount()
  }
}

// eslint-disable-next-line react-refresh/only-export-components
const Component = () => {
  const { isCurrentUserHasPermission } = useAppUIContext()

  return (
    <div>
      <div>Hello world!</div>
      <div hidden={!isCurrentUserHasPermission({ action: CrudType.READ, resource: 'ADMIN:NONEXISTENTRESOURCE' })}>Hello world!</div>
    </div>
  )
}

HostContext​

HostContext は、Admin Portal が mount() 関数の第 2 引数として渡すオブジェクトです。このオブジェクトは、認証済みの AGS API 呼び出しの実行や現在のユーザーのパーミッションチェックに必要なものを、すべて App UI に提供します。

interface HostContext {
  /** Core SDK configuration passed from the Admin Portal. Pass this to AppUIContextProvider. */
  sdkConfig: SdkConfigOptions
  /** The base path the Admin Portal uses to route requests for this App UI. */
  basePath: string
  /** Returns true if the current portal user has the given permission. */
  isCurrentUserHasPermission: (permission: CrudRolePermission) => boolean
}

hostContext.sdkConfig と hostContext.isCurrentUserHasPermission を直接 AppUIContextProvider に渡します。AppUIModule の完全な例で、このパターンを示しています。

AppUIContextProvider​

AppUIContextProvider は、AccelByte SDK を初期化し、App UI の認証状態とパーミッション状態を管理する React コンテキストプロバイダーです。このコンポーネントでアプリケーションのルートをラップします。

interface AppUIContextProviderProps {
  sdkConfig: SdkConfigOptions
  /**
   * Provided by the host in production. Omit in development —
   * the provider will fall back to its own PermissionGuard.
   */
  isCurrentUserHasPermission?: (permission: CrudRolePermission) => boolean
  children: ReactNode
}

プロバイダーは NODE_ENV を介して環境を検出し、それに応じて動作を切り替えます。

項目開発環境本番環境
認証OAuth2 認可コードを交換し、トークンを自動的にリフレッシュしますスキップされます。Admin Portal が認証を管理します。
パーミッションIAM から現在のユーザーとすべてのロールを取得し、パーミッションチェッカーを設定しますAdmin Portal から渡された isCurrentUserHasPermission を使用します

使用例:

import { AppUIContextProvider } from '@accelbyte/sdk-extend-app-ui'

function App() {
  return (
    <AppUIContextProvider sdkConfig={sdkConfig}>
      <YourAppContent />
    </AppUIContextProvider>
  )
}

useAppUIContext​

useAppUIContext は、AppUIContextProvider によって提供される初期化済みの SDK インスタンスとパーミッションユーティリティへのアクセスを子コンポーネントに提供する React フックです。

interface AppUIContextValue {
  /** Initialized AccelByteSDK instance. Use this to call AGS APIs. */
  sdk: AccelByteSDK
  /** True while user data or roles are loading. */
  isLoading: boolean
  /** Returns true if the current user has the given permission. */
  isCurrentUserHasPermission: (permission: CrudRolePermission) => boolean
}

使用例:

isCurrentUserHasPermission を使用して、現在のユーザーのアクセスレベルに応じて UI 要素を条件付きで表示します。CrudType からの action と、Extend サービスが必要とするパーミッション resource 文字列を持つ CrudRolePermission オブジェクトを渡します。

import { useAppUIContext, CrudType } from '@accelbyte/sdk-extend-app-ui'

function TournamentListHeader() {
  const { isCurrentUserHasPermission } = useAppUIContext()

  return (
    <p hidden={!isCurrentUserHasPermission({ action: CrudType.READ, resource: 'ADMIN:RANDOMRESOURCE' })}>
      This header is only visible to users with READ access on ADMIN:RANDOMRESOURCE
    </p>
  )
}

CrudType は、CREATE、READ、UPDATE、DELETE という値を持つ enum です。ADMIN:RANDOMRESOURCE は、サービスのパーミッションリソース文字列に置き換えてください。リソース文字列がどのように構成されているかについては、Permission Fundamentals を参照してください。

devProxyPlugin​

devProxyPlugin は、ローカル開発中に API リクエストを AGS バックエンドにプロキシし、CORS エラーを回避する Vite プラグインです。vite.config.ts に追加します。

function devProxyPlugin(options: {
  /** AGS backend base URL. Must match the baseURL registered in your IAM OAuth client. */
  baseUrl: string
  /** OAuth2 redirect URI. Must match the redirect URI registered in your IAM OAuth client. */
  redirectURI: string
}): Plugin
注記

baseUrl と redirectURI の両方は、IAM OAuth クライアントに登録された値と一致する必要があります。これは、Extend Helper CLI の setup-env コマンドによって既に処理されています。

/proxy/* へのすべてのリクエストは AGS バックエンドに転送されます。開発環境では、SDK の baseURL を /proxy に指定してください。

const sdkConfig = {
  baseURL: import.meta.env.DEV ? '/proxy' : 'https://your-ags-instance.accelbyte.io'
  // ...
}

このプラグインは、Public Cloud のサブドメインルーティングも処理します。Public Cloud では、各 namespace が独自のサブドメインから提供されます（例: spaceshooter-game.prod.gamingservices.accelbyte.io）。AGS は、受信リクエストが正しいサブドメインから発信されていることを確認するために Referer ヘッダーを検証します。この検証は、リクエストが localhost から発信されるローカル開発中は失敗します。これを回避するために、プラグインは access_token クッキーを読み取り、そこから現在のnamespaceを抽出し、期待されるサブドメイン URL に一致するように、プロキシされた各リクエストに Referer ヘッダーを設定します。

Types​

エクスポートされたすべての型の完全な TypeScript インターフェース定義については、npm 上の @accelbyte/sdk-extend-app-ui パッケージを参照してください。

型説明
SdkConfigOptionsAccelByte.SDK() に渡されるコア設定
HostContextホストから mount() に渡されるオブジェクト: sdkConfig、basePath、isCurrentUserHasPermission
AppUIModuleアプリモジュールが実装する必要があるコントラクト: mount(container, context): () => void
CrudRolePermissionisCurrentUserHasPermission で使用されるパーミッション記述子
CrudType文字列値 CREATE、READ、UPDATE、DELETE を持つ CRUD アクションの enum

Next steps​

に最終更新
On this page