Context & Session

When the App Bridge handshake completes, the admin sends a whatalo:context payload containing everything your plugin needs to know about the current session — the store it's installed in, the logged-in user, the active UI theme, and which page is displayed.

WhataloContext is intentionally lightweight. It helps your iframe understand the current session and admin shell, but it is not the source of truth for store metadata or business resources.

Use these rules:

• Need storeId, storeName, locale, theme, or current page? Use useAppBridge() / useWhataloContext()
• Need frontend read access to store data like orders, products, or store.timezone? Use useWhataloData()
• Need backend reads, writes, or trusted server logic? Use WhataloClient

WhataloContext Type

interface WhataloContext {
  storeId: string;        // Public store identifier
  storeName: string;      // Store display name
  locale: string;         // e.g., "es", "en"
  theme: "light" | "dark";
  user: WhataloUser;
  appId: string;          // Your plugin ID from the manifest
  currentPage: string;    // Active page path — e.g., "dashboard", "settings"
  initialHeight: number;  // Suggested iframe height in pixels
}

interface WhataloUser {
  id: string;
  name: string;
  email: string;
  role: "owner" | "admin" | "editor" | "staff" | "viewer";
}

user.name is a display label only. Do not treat it as a verified profile name. For identity-sensitive UI, prefer user.email and user.role.

Accessing Context

import { useAppBridge } from "@whatalo/plugin-sdk/bridge";

function MyComponent() {
  const { storeId, storeName, user, locale, theme, isReady } = useAppBridge();

  if (!isReady) return <Spinner />;

  return (
    <div>
      <p>
        Store: {storeName} ({storeId})
      </p>
      <p>
        User: {user.email} — Role: {user.role}
      </p>
      <p>
        Locale: {locale} — Theme: {theme}
      </p>
    </div>
  );
}

Default Values Before isReady

The hook returns safe defaults while the handshake is in progress. This prevents null-check errors in your render logic.

Always check isReady before using context values in logic that depends on them (API calls, conditional rendering based on user.role, etc.).

Role-Based Access

Use user.role to conditionally expose features. Roles are set by the store owner and cannot be modified by plugins.

const { user } = useAppBridge();

return (
  <div>
    {user.role === "owner" && <DangerZoneSettings />}
    {(user.role === "owner" || user.role === "admin") && <BulkActions />}
    <ReadOnlyView />
  </div>
);

currentPage and Multi-Page Plugins

currentPage reflects which page the user is currently viewing in your plugin. It matches the path field you defined in adminUI.pages inside the manifest. Use it to render the correct view:

const { currentPage } = useAppBridge();

switch (currentPage) {
  case "settings":
    return <SettingsPage />;
  case "dashboard":
  default:
    return <DashboardPage />;
}

See Navigation for the full routing pattern.

Context Updates

The admin pushes updated context automatically when:

• The user navigates to a different page in your plugin
• The admin theme changes (light ↔ dark)

Your component re-renders with the new values because useAppBridge() is backed by a React context that updates on every incoming whatalo:context message.