Appoxo 网络 SDK

使用 Iframe 通讯将微型应用程序嵌入您的桌面应用程序 .

快速启动

import { AppboxoWebSDK } from "@appboxo/web-sdk";

const sdk = new AppboxoWebSDK({
  clientId: "your-client-id",
  appId: "your-app-id"
});

// Get auth code from your backend
const authCode = await fetch('/api/auth-code').then(r => r.json());
sdk.setAuthCode(authCode);

// Mount miniapp (SDK will automatically fetch URL from API)
await sdk.mount({
  container: document.getElementById("miniapp")
});

安装

npm install @appboxo/web-sdk
# or
pnpm install @appboxo/web-sdk

配置

const sdk = new AppboxoWebSDK({
  clientId: string;      // Required
  appId: string;         // Required
  userId?: string;       // Optional, user reference identifier
  baseUrl?: string;      // Optional, default: "https://dashboard.boxo.io/api/v1"
  sandboxMode?: boolean;  // Optional, default: false
  debug?: boolean;       // Optional, default: false. When true, enables all console logs for debugging. When false, no console logs are output.
  locale?: string;       // Optional, locale/language code (e.g., 'en', 'en-US', 'ru', 'zh-CN')
  theme?: 'dark' | 'light' | 'system'; // Optional, theme/color scheme preference (default: 'system')
  onGetAuthCode?: () => Promise<string>; // Optional, for automatic auth code retrieval
  onGetAuthTokens?: () => Promise<LoginResponse>; // Optional, for direct auth tokens
  onPaymentRequest?: (params: PaymentRequest) => Promise<PaymentResponse>; // Optional, for handling payment requests
});

认证

OAuth 流量 :

sdk.setAuthCode(authCode);

或提供回电:

const sdk = new AppboxoWebSDK({
  clientId: "your-client-id",
  appId: "your-app-id",
  onGetAuthCode: async () => {
    const res = await fetch('/api/generate-auth-code');
    return (await res.json()).auth_code;
  }
});

直接认证流 :

sdk.onAuth(async () => {
  const response = await fetch('/api/get-miniapp-tokens');
  const tokens = await response.json();
  sdk.setAuthTokens(tokens.access_token, tokens.refresh_token);
});

或使用回调:

const sdk = new AppboxoWebSDK({
  clientId: "your-client-id",
  appId: "your-app-id",
  onGetAuthTokens: async () => {
    const res = await fetch('/api/get-miniapp-tokens');
    const result = await res.json();
    return {
      token: result.access_token,
      refresh_token: result.refresh_token
    };
  }
});

或者直接设置符号 :

const tokens = await getTokensFromBackend();
sdk.setAuthTokens(tokens.access_token, tokens.refresh_token);

SDK会尝试这些顺序:

1. 预设的符号( A)setAuthTokens(中文(简体) )
2. 直接认证召回( N)onGetAuthTokens(中文(简体) )
3. OAuth 认证代码 (setAuthCode 或者说 onGetAuthCode 调用)

付款处理

当一个小程序打电话 appboxo.pay()SDK会打电话给你 onPaymentRequest 调用。 处理付款并返回结果.

付款状况值: 'success', (中文(简体) ), 'failed',或 'cancelled'。 。 。 .

const sdk = new AppboxoWebSDK({
  clientId: "your-client-id",
  appId: "your-app-id",
  onPaymentRequest: async (paymentData) => {
    // Process payment with your backend
    const response = await fetch('/api/payments/process', {
      method: 'POST',
      body: JSON.stringify(paymentData)
    });
    const result = await response.json();
    
    return {
      ...paymentData,
      status: result.status, // 'success', 'failed', or 'cancelled'
      hostappOrderId: result.orderId,
      transactionId: result.transactionId, // optional
    };
  },
});

// Optional: listen for payment completion
sdk.onPaymentComplete((success, data) => {
  if (success) {
    console.log('Payment succeeded:', data);
  }
});

重要注释 :

• 何时 onPaymentRequest 设定, SDK 自动告诉它支持的小程序 AppBoxoWebAppPay,所以它可以调用 appboxo.pay()。 。 。 .
• 若为 onPaymentRequest 未配置,则付款请求会失败。 启用 debug: true 以查看错误消息.
• 关于 debug 模式 :
  • debug: false (默认):没有控制台日志是输出. 适于出产.
  • debug: true:所有SDK操作都登录到控制台. 有利于发展和解决问题.
  • 这个 debug 选项不影响 SDK 功能 - 它只控制控制控制台记录 .

地方/语言

设定本地语区/ 语言代码传递到小app. 该地块将被纳入InitData响应.

// Set locale during initialization
const sdk = new AppboxoWebSDK({
  clientId: "your-client-id",
  appId: "your-app-id",
  locale: "en-US"  // or 'ru', 'zh-CN', etc.
});

// Or set locale dynamically
sdk.setLocale("ru");

地方通过 InitData.data.locale 下一个 AppBoxoWebAppGetInitData 请求.

重要注释 :

• 如果你打电话 setLocale() 在迷你app已经加载后, 语言将包含在下一个 InitData 请求中 。 迷你app可能需要重新装入或再次请求InitData来接收更新后的语言.
• 为了确保立即提供该地块,在SDK初始化期间或打电话之前设置该地块 mount()。 。 。 .

主题/ 黑暗模式

设置主题/ 颜色方案首选项以传递到小应用程序 。 主题将纳入InitData回复.

// Set theme during initialization
const sdk = new AppboxoWebSDK({
  clientId: "your-client-id",
  appId: "your-app-id",
  theme: "dark"  // or 'light', 'system'
});

// Or set theme dynamically
sdk.setTheme("light");

主题通过 InitData.data.theme 下一个 AppBoxoWebAppGetInitData 请求.

主题值 :

• 'dark': 强制黑暗模式
• 'light': 强制灯光模式
• 'system': 使用系统首选项(默认)

重要注释 :

• 如果你打电话 setTheme() 在迷你app已经加载后,主题将包含在下个 InitData 请求中. 迷你app可能需要重新装入或再次请求InitData来接收更新后的主题.
• 为了确保立即提供主题,在 SDK 初始化期间或呼叫前设置 mount()。 。 。 .

注销

这个 logout() 方法清除主机应用的存储和SDK的内部认证数据.

sdk.logout();

重要注释 :

• 这只能澄清 主机应用程序 localStorage 财务报告和审定财务报表 sessionStorage
• Miniapp的存储是独立的(不同来源),由于浏览器安全限制而无法从主机应用程序中清除
• SDK会通过微程序发送登出通知 postMessage 使用标准 appboxo-host-response 格式
• 迷你游戏应该听 AppBoxoWebAppLogout 清除自己存储的处理器
• SDK的内部 authCode 财务报告和审定财务报表 authTokens 也被清除

最小化集成 :

要在您的小app中接收登出通知, 请添加一个消息倾听器 :

useEffect(() => {
  const handleMessage = (event: MessageEvent) => {
    if (
      event.data?.type === "appboxo-host-response" &&
      event.data?.handler === "AppBoxoWebAppLogout" &&
      event.data?.data?.action === "logout"
    ) {
      // Clear miniapp's storage
      localStorage.clear();
      sessionStorage.clear();
    }
  };
  
  window.addEventListener("message", handleMessage);
  return () => window.removeEventListener("message", handleMessage);
}, []);

方法

活动

SDK处理这些小型应用事件:

• AppBoxoWebAppLogin - 用户认证
• AppBoxoWebAppPay - 付款处理
• AppBoxoWebAppGetInitData - 初步数据要求
• AppBoxoWebAppCustomEvent - 自定义活动

实例

反应示例

import { AppboxoWebSDK } from "@appboxo/web-sdk";
import type { PaymentRequest, PaymentResponse } from "@appboxo/web-sdk";

function App() {
  const iframeRef = useRef<HTMLIFrameElement>(null);
  const [sdk, setSdk] = useState<AppboxoWebSDK | null>(null);

  useEffect(() => {
    const s = new AppboxoWebSDK({ 
      clientId: "your-client-id", 
      appId: "your-app-id",
      onPaymentRequest: async (paymentData: PaymentRequest): Promise<PaymentResponse> => {
        const response = await fetch('/api/payments/process', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(paymentData)
        });
        const result = await response.json();
        
        return {
          ...paymentData,
          status: result.status,
          hostappOrderId: result.hostappOrderId,
        };
      },
    });
    
    s.setAuthCode("your-auth-code");
    
    s.onLoginComplete((success, data) => {
      console.log('Login:', success ? 'success' : 'failed', data);
    });
    s.onPaymentComplete((success, data) => {
      console.log('Payment:', success ? 'success' : 'failed', data);
    });
    
    setSdk(s);
    return () => s.destroy();
  }, []);

  useEffect(() => {
    const fetchUrl = async () => {
      if (sdk && iframeRef.current) {
        const url = await sdk.getMiniappUrl();
        iframeRef.current.src = url;
      }
    };
    fetchUrl();
  }, [sdk]);

  const handleLoad = () => {
    if (sdk && iframeRef.current) {
      sdk.setIframe(iframeRef.current);
      sdk.initialize();
    }
  };

  return <iframe ref={iframeRef} onLoad={handleLoad} src="" />;
}

使用挂载帮助

// SDK will automatically fetch miniapp URL from API
await sdk.mount({
  container: '#miniapp-container',
  className: 'miniapp-iframe'
});

造型通过CSS处理:

.miniapp-container {
  width: 100%;
  height: 500px;
}

.miniapp-iframe {
  width: 100%;
  height: 100%;
  border: none;
}

许可证

阿帕奇 - 2.0