useOpenAIGlobal

Access global OpenAI context and utilities within your widget. This hook provides access to OpenAI-specific features, configuration, and shared utilities that are available across the ChatGPT environment.

Usage

import { useOpenAIGlobal } from '@chatgpt-apps/sdk';

function MyWidget() {
  const openAI = useOpenAIGlobal();

  return (
    <div>
      <p>Model: {openAI.model}</p>
      <p>Version: {openAI.version}</p>
      <button onClick={() => openAI.trackEvent('widget_opened')}>
        Track Event
      </button>
    </div>
  );
}

Parameters

This hook accepts no parameters.

Return Type

Returns an object with OpenAI context and utilities:

interface OpenAIGlobalContext {
  // Configuration
  model: string;
  version: string;
  environment: 'production' | 'staging' | 'development';
  
  // User context
  user?: {
    id: string;
    preferences: Record<string, unknown>;
  };
  
  // Utilities
  trackEvent: (eventName: string, metadata?: Record<string, unknown>) => void;
  getConfig: <T = unknown>(key: string, defaultValue?: T) => T;
  
  // Feature flags
  features: {
    [featureName: string]: boolean;
  };
}

Property	Type	Description
`model`	`string`	The current OpenAI model being used
`version`	`string`	SDK or API version
`environment`	`string`	Current environment (production, staging, development)
`user`	`object`	Optional user context with ID and preferences
`trackEvent`	`function`	Analytics event tracking function
`getConfig`	`function`	Retrieve configuration values
`features`	`object`	Feature flags availability

Example

Basic Context Access

import { useOpenAIGlobal } from '@chatgpt-apps/sdk';

function InfoWidget() {
  const openAI = useOpenAIGlobal();

  return (
    <div className="info-panel">
      <h3>Environment Info</h3>
      <ul>
        <li>Model: {openAI.model}</li>
        <li>Version: {openAI.version}</li>
        <li>Environment: {openAI.environment}</li>
      </ul>
    </div>
  );
}

Event Tracking

import { useOpenAIGlobal } from '@chatgpt-apps/sdk';

function AnalyticsWidget() {
  const { trackEvent } = useOpenAIGlobal();

  const handleAction = (actionType: string) => {
    // Track the user action
    trackEvent('widget_action', {
      action: actionType,
      timestamp: Date.now(),
    });
  };

  return (
    <div>
      <button onClick={() => handleAction('export')}>
        Export Data
      </button>
      <button onClick={() => handleAction('share')}>
        Share
      </button>
      <button onClick={() => handleAction('settings')}>
        Settings
      </button>
    </div>
  );
}

Configuration Access

import { useOpenAIGlobal } from '@chatgpt-apps/sdk';

function ConfigWidget() {
  const { getConfig } = useOpenAIGlobal();

  // Get config with default values
  const theme = getConfig<string>('theme', 'light');
  const maxItems = getConfig<number>('max_items', 10);
  const enableBeta = getConfig<boolean>('beta_features', false);

  return (
    <div className={theme}>
      <p>Max items: {maxItems}</p>
      {enableBeta && <BetaFeatures />}
    </div>
  );
}

Feature Flags

import { useOpenAIGlobal } from '@chatgpt-apps/sdk';

function FeatureWidget() {
  const { features } = useOpenAIGlobal();

  return (
    <div>
      <h3>Widget Features</h3>
      
      {features.advanced_search && (
        <AdvancedSearch />
      )}
      
      {features.data_export && (
        <ExportButton />
      )}
      
      {features.realtime_updates ? (
        <LiveDataFeed />
      ) : (
        <StaticDataView />
      )}
    </div>
  );
}

User Context

import { useOpenAIGlobal } from '@chatgpt-apps/sdk';

function PersonalizedWidget() {
  const { user } = useOpenAIGlobal();

  if (!user) {
    return <div>Please sign in to use this widget</div>;
  }

  const theme = user.preferences?.theme ?? 'light';
  const language = user.preferences?.language ?? 'en';

  return (
    <div className={`widget ${theme}`} lang={language}>
      <p>Welcome, user {user.id}</p>
      <PersonalizedContent userId={user.id} />
    </div>
  );
}

Complete Integration

import { useOpenAIGlobal } from '@chatgpt-apps/sdk';

function ComprehensiveWidget() {
  const openAI = useOpenAIGlobal();

  useEffect(() => {
    // Track widget initialization
    openAI.trackEvent('widget_initialized', {
      model: openAI.model,
      environment: openAI.environment,
    });
  }, [openAI]);

  const handleSettingChange = (key: string, value: unknown) => {
    openAI.trackEvent('setting_changed', { key, value });
  };

  return (
    <div>
      <header>
        <span>Model: {openAI.model}</span>
        {openAI.features.debug_mode && (
          <DebugBadge environment={openAI.environment} />
        )}
      </header>
      
      <main>
        <SettingsPanel
          theme={openAI.getConfig('theme', 'light')}
          onChange={handleSettingChange}
        />
      </main>
    </div>
  );
}

Notes

The available context may vary based on the host environment
Some properties may be undefined if not provided by the host
Use getConfig with default values for safe configuration access
Event tracking is optional and may be disabled in some environments
Feature flags allow progressive rollout of widget capabilities
User context is only available when the user is authenticated

useOpenAIGlobal

On this page