跳到主要内容

Midasbuy Minigame SDK API 协议

1. 概述​

Midasbuy Minigame SDK 是一个统一的小游戏 SDK 加载器和适配器，提供一致的 API 接口用于 Menu、Payment 和 Login 功能模块。

2. SDK 集成​

<script src="https://cdn.midasbuy.com/js/minigame.stable.js"></script>

3. API 协议​

3.1 初始化 midas.minigame(options)​

const minigameApi = midas.minigame({
  // 基础配置
  appid: '1460000904',
  region: 'us',
  language: 'en',
  sandbox: 1,
  shopcode: 'xxxinapp',
  
  // Menu 模块配置, 可选
  menu: {
    isWithPcHeader: true,
    isLandscapeMode: false  // 竖屏模式（导航条），默认值
  },
  
  // Payment 模块配置, 可选
  payment: {
    openid: '1018553529511732', // 减少坏账率，可不传
    charac_name: 'Player1', // 减少坏账率，可不传
  },
  
  // Login 模块配置, 可选
  login: {
    debug: true,
    timeout: 30000
  }
});

参数说明​

参数类型必填描述
appidstring是应用 ID
regionstring是地区代码，2位字符
languagestring否语言代码，默认 'en'
sandboxnumber否环境：0-生产，1-沙箱，2-测试，默认 0
shopcodestring否商店代码
menuMenuConfig否Menu 模块配置
paymentPaymentConfig否Payment 模块配置
loginLoginConfig否Login 模块配置
interface MenuConfig {
  isWithPcHeader?: boolean;   // PC端是否包含顶部header
  isLandscapeMode?: boolean;  // 启用横屏模式（气泡样式菜单），默认 false
}

PaymentConfig 类型​

interface PaymentConfig {
  openid?: string;           // 用户 openid
  charac_name?: string;      // 角色名称
}

LoginConfig 类型​

interface LoginConfig {
  debug?: boolean;                          // 调试模式
  timeout?: number;                         // 请求超时时间(毫秒)
}

3.2 菜单功能​

菜单模块支持两种显示模式：

  • 竖屏模式（导航条）：传统的顶部导航条样式，适用于移动端竖屏方向
  • 横屏模式（气泡菜单）：浮动气泡样式菜单，适用于移动端横屏方向

3.2.1 显示菜单 minigameApi.showMenu(options)​

竖屏模式示例（导航条）：

// 初始化竖屏模式
const minigameApi = midas.minigame({
  appid: '1460000904',
  region: 'us',
  menu: {
    isLandscapeMode: false  // 竖屏模式（默认）
  }
});

// 显示竖屏菜单
minigameApi.showMenu({
  gradually: true
});

横屏模式示例（气泡菜单）：

// 初始化横屏模式
const minigameApi = midas.minigame({
  appid: '1460000904',
  region: 'us',
  menu: {
    isLandscapeMode: true   // 横屏模式（气泡样式）
  }
});

// 显示横屏菜单
minigameApi.showMenu({
  gradually: true
});
参数说明​
参数类型必填描述
graduallyboolean否是否渐进式显示，默认 true

3.2.2 隐藏菜单 minigameApi.hideMenu(options)​

// 隐藏游戏菜单（适用于竖屏和横屏两种模式）
minigameApi.hideMenu({
  gradually: true
});
参数说明​
参数类型必填描述
graduallyboolean否是否渐进式隐藏，默认 true

3.3 支付功能​

3.3.1 显示支付页面 minigameApi.showPayment(options)​

事件监听方式（传统）：

// 使用事件监听器显示支付页面
minigameApi.on('payment:success', (data) => {
  console.log('支付成功:', data);
});

minigameApi.on('payment:failed', (error) => {
  console.log('支付失败:', error);
});

minigameApi.showPayment({
  params: {
    game_openid: '1018553529511732',
    role_id: '1555629938',
    product_id: 'coins_01-midasbuy'
  },
  extra: {
    hideResultPage: true
  }
});

Promise 方式（推荐）：

// 使用 Promise 显示支付页面
minigameApi.showPayment({
  params: {
    game_openid: '1018553529511732',
    role_id: '1555629938',
    product_id: 'coins_01-midasbuy',
    server_id: 'server_001'
  },
  extra: {
    hideResultPage: true
  }
})
.then(data => {
  console.log('支付成功:', data);
  // data 包含: { order_no, openid, order_no_hash }
})
.catch(error => {
  console.log('支付错误:', error);
  
  // 处理不同类型的错误
  switch(error.type) {
    case 'failed':
      console.log('支付失败:', error.data);
      break;
    case 'hide':
      console.log('支付弹窗被关闭');
      break;
    case 'queryChannelsFailed':
      console.log('加载支付渠道失败:', error.data);
      break;
  }
});

// 使用 async/await
async function handlePayment() {
  try {
    const result = await minigameApi.showPayment({
      params: {
        game_openid: '1018553529511732',
        role_id: '1555629938',
        product_id: 'coins_01-midasbuy',
        server_id: 'server_001'
      }
    });
    console.log('支付成功:', result);
  } catch (error) {
    console.log('支付失败:', error.type, error.message);
  }
}
参数说明​
参数类型必填描述
paramsPaymentParams是支付参数
extraPaymentExtra否支付额外参数

PaymentParams 类型​

interface PaymentParams {
  game_openid: string;    // 游戏用户 ID
  role_id: string;        // 角色 ID
  product_id: string;     // 商品 ID
  server_id?: string;     // 游戏分区ID
  is_vip_product?: boolean; // 是否VIP商品
}

PaymentExtra 类型​

interface PaymentExtra {
  hideResultPage?: boolean; // 是否隐藏结果页面
}

PaymentError 类型​

interface PaymentError extends Error {
  code: string;                                    // 错误代码
  type: 'failed' | 'hide' | 'queryChannelsFailed'; // 错误类型
  data?: any;                                      // 额外错误数据
  timestamp: number;                               // 错误时间戳
}
错误类型​
类型描述发生时机
failed支付交易失败用户支付未成功
hide支付弹窗关闭用户关闭了支付弹窗
queryChannelsFailed加载支付渠道失败网络错误或商品无效

3.3.2 隐藏支付页面 minigameApi.hidePayment()​

// 隐藏支付页面
minigameApi.hidePayment();

3.4 登录功能​

3.4.1 用户登录 minigameApi.login(options)​

回调方式:

// 使用回调函数的用户登录
minigameApi.login({
  success: function(result) {
    console.log('登录成功:', result);
  },
  fail: function(error) {
    console.log('登录失败:', error);
  }
});

Promise 方式:

// 使用 Promise 的用户登录
minigameApi.login()
  .then(result => {
    console.log('登录成功:', result);
  })
  .catch(error => {
    console.log('登录失败:', error);
  });

// 或者使用 async/await
async function handleLogin() {
  try {
    const result = await minigameApi.login();
    console.log('登录成功:', result);
  } catch (error) {
    console.log('登录失败:', error);
  }
}

参数说明:

参数类型必填说明
successFunction否登录成功回调函数
failFunction否登录失败回调函数

注意: 使用 Promise 方式时，可以省略 success 和 fail 回调函数，改用 .then() 和 .catch() 方法。

成功回调参数:

{
  code: 0,
  message: 'success',
  data: {
    jwtToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    expiresIn: 3600,
    refreshToken: 'rt_xxxxxxxxxxxxxxxx'
  }
}

失败回调参数:

{
  code: -1,
  message: '错误描述',
  error: 'ERROR_CODE'
}

3.5 商品功能​

3.5.1 获取商品数据 minigameApi.getProductsData(params)​

基于“人货场”的理念，在初始化时传入了“场”，在此通过传入“人”即游戏用户信息来获取“货”即货架商品信息，用于在游戏中展示。

Promise 方式：

// 获取商品数据
minigameApi.getProductsData({
  game_openid: '1018553529511732',
  role_id: '1555629938',
  server_id: 'server_001'
})
.then(data => {
  console.log('获取商品数据成功:', data);
  // data 包含: { products: ProductItem[] }
})
.catch(error => {
  console.log('获取商品数据失败:', error);
});

// 使用 async/await
async function handleGetProducts() {
  try {
    const result = await minigameApi.getProductsData({
      game_openid: '1018553529511732',
      role_id: '1555629938',
      server_id: 'server_001'
    });
    console.log('商品数据:', result.products);
  } catch (error) {
    console.log('获取商品失败:', error);
  }
}
参数说明​
参数类型必填描述
game_openidstring是游戏用户 ID
role_idstring是角色 ID
server_idstring否游戏分区ID
ProductItem 类型​
interface ProductItem {
  product_id: string;            // midasbuy 内部的物品 ID
  game_product_id: string;       // 业务侧的物品 ID
  quantity: number;              // 游戏币或道具数量 (结合物品类型)
  product_type: 'currency' | 'item'; // 物品类型：currency(游戏币) 或 item(道具)
  product_icon: string;          // 物品图片URL
  name: string;                  // 物品名称
  price_info: {
    price: string;               // 当前价格，如：'69.99'
    original_price: string;      // 原价，如：'77.99'
    currency: string;            // 币种，如：'HKD'
    display_price: string;       // 展示价格（含币种），如：'69.99 HKD'
    display_original_price: string; // 展示原价（含币种），如：'77.99 HKD'
  };
  bonus: {
    virtual_currency_quantity: number; // 赠送游戏币数量
    virtual_item_list: {         // 赠送道具物品列表
      product_id: string;        // 赠送的道具对应的 midasbuy 内部的物品 ID
      game_product_id: string;   // 赠送的道具对应的业务侧的物品 ID
      name: string;              // 赠送道具名称
      quantity: number;          // 赠送道具数量
      icon: string;              // 赠送道具图片URL
    }[];
  };
  meta: any;                     // 货架处理前的源数据，一般无需关注
}

product_id 和 game_product_id 一般是一一对应的

ProductItem示例：

const exampleProduct: ProductItem = {
  product_id: "600_coins_vip",
  game_product_id: "600_coins",
  quantity: 600,
  product_type: "currency",
  product_icon: "https://cdn.midasbuy.com/images/apps/pubgm/1599546041426W8hmErMS.png",
  name: "600 UnknownCash",
  price_info: {
    price: "69.99",
    original_price: "77.99",
    currency: "HKD",
    display_price: "69.99 HKD",
    display_original_price: "77.99 HKD"
  },
  bonus: {
    virtual_currency_quantity: 60,
    virtual_item_list: [
      {
        product_id: "MP_DEFAULT_MOBILE_COIN",
        game_product_id: "MP_DEFAULT_MOBILE_COIN",
        name: "Event Voucher (Use in event)",
        quantity: 1,
        icon: "https://cdn.midasbuy.com/images/4113%20%281%29.2c5fa435.png"
      }
    ]
  },
  meta: { /* 原始货架数据 */ }
};

meta 是货架处理前的源数据，一般无需关注。类型参考 https://midasbuy-develop.pages.woa.com/master/%E5%BE%AE%E6%9C%8D%E5%8A%A1%E4%BB%8B%E7%BB%8D/%E8%B4%A7%E6%9E%B6%E6%9C%8D%E5%8A%A1/3.%20%E5%8D%8F%E8%AE%AE%E8%AE%BE%E8%AE%A1/%E8%B4%A7%E6%9E%B6%E6%9C%8D%E5%8A%A1%E5%8D%8F%E8%AE%AE/#shelfproduct

ProductsResult 类型​
interface ProductsResult {
  products: ProductItem[];  // 商品项目数组
}

3.6 事件监听 minigameApi.on(event, callback)​

// 游戏菜单事件
minigameApi.on('menu:show', (data) => {
  console.log('游戏菜单显示成功', data);
});

minigameApi.on('menu:hide', () => {
  console.log('游戏菜单隐藏');
});

minigameApi.on('menu:error', (error) => {
  console.error('游戏菜单错误', error);
});

// 支付事件
minigameApi.on('payment:success', (data) => {
  console.log('支付成功', data);
});

minigameApi.on('payment:failed', (error) => {
  console.log('支付失败', error);
});

minigameApi.on('payment:hide', () => {
  console.log('支付页面隐藏');
});

minigameApi.on('payment:queryChannelsFailed', (error) => {
  console.log('查询渠道失败', error);
});

// 登录事件
minigameApi.on('login:success', (data) => {
  console.log('登录成功，jwtToken:', data.jwtToken || data?.data?.jwtToken);
});

minigameApi.on('login:failed', (error) => {
  console.log('登录失败', error);
});

minigameApi.on('login:statusChanged', (status) => {
  console.log('登录状态变化', status);
});

minigameApi.on('login:tokenExpired', () => {
  console.log('Token已过期');
});

// 商品事件
minigameApi.on('products:success', (data) => {
  console.log('商品数据加载成功', data);
});

minigameApi.on('products:failed', (error) => {
  console.log('商品数据加载失败', error);
});

// 通用事件
minigameApi.on('sdk:loaded', (modules) => {
  console.log('SDK加载完成', modules);
});

minigameApi.on('sdk:error', (error) => {
  console.error('SDK错误', error);
});

事件类型​

事件名描述回调参数
menu:show游戏菜单显示成功{ res: string, size?: { width?: string, height?: string } }
menu:hide游戏菜单隐藏无
menu:error游戏菜单错误Error
payment:success支付成功{ order_no: string, openid: string, order_no_hash: string }
payment:failed支付失败Error
payment:hide支付页面隐藏无
payment:queryChannelsFailed查询渠道失败Error
login:success登录成功{ jwtToken: string }
login:failed登录失败Error
login:statusChanged登录状态变化'logged_in' | 'logged_out' | 'token_expired'
login:tokenExpiredToken过期无
products:success商品数据加载成功ProductsResult
products:failed商品数据加载失败Error
sdk:loadedSDK加载完成string[] (已加载的模块列表)
sdk:errorSDK错误Error

3.7 取消事件监听 minigameApi.off(event, callback?)​

// 取消特定回调
minigameApi.off('payment:success', callback);

// 取消所有回调
minigameApi.off('payment:success');

3.8 工具方法​

3.8.1 获取模块实例 minigameApi.getModule(module)​

获取特定模块实例的直接访问权限，用于高级用法。

// 获取菜单模块实例
const menuModule = minigameApi.getModule('menu');
if (menuModule) {
  // 直接访问菜单模块方法
  menuModule.show({ gradually: false });
}

// 获取支付模块实例
const paymentModule = minigameApi.getModule('payment');
if (paymentModule) {
  // 直接访问支付模块方法
  paymentModule.emit('checkout', params);
}

// 获取登录模块实例
const loginModule = minigameApi.getModule('login');
if (loginModule) {
  // 直接访问登录模块方法
  const isLoggedIn = loginModule.isLoggedIn();
}
参数说明​
参数类型必填描述
modulestring是模块名称：'menu'、'payment' 或 'login'
返回值​

返回对应的模块实例，如果模块未加载或无效则返回 null。

3.8.2 隐藏所有模块 minigameApi.hideAll()​

// 隐藏所有模块（菜单、支付等）
minigameApi.hideAll();

4. 错误处理​

4.1 错误类型​

interface MinigameError extends Error {
  code: string;
  module?: 'menu' | 'payment' | 'core';
  details?: any;
}

4.2 错误代码​

错误代码描述
INIT_FAILED初始化失败
MODULE_NOT_LOADED模块未加载
INVALID_PARAMS无效参数
SHOW_FAILED显示失败
HIDE_FAILED隐藏失败
PAYMENT_FAILED支付失败
NETWORK_ERROR网络错误

4.3 全局错误处理​

minigameApi.setErrorHandler((error) => {
  console.error('Minigame SDK Error:', error);
  // 自定义错误处理逻辑
});

5. 类型定义​

declare namespace midas {
  interface MinigameAPI {
    showMenu(options?: MenuShowOptions): Promise<ShowResult>;
    hideMenu(options?: MenuHideOptions): void;
    showPayment(options: PaymentShowOptions): Promise<PaymentResult>;
    hidePayment(): void;
    hideAll(): void;
    login(options: LoginOptions): Promise<LoginResult>;
    getLoginStatus(): boolean;
    logout(): void;
    getProductsData(params: ProductsParams): Promise<ProductsResult>;
    on(event: string, callback: Function): void;
    off(event: string, callback?: Function): void;
    getModule(module: 'menu' | 'payment' | 'login'): any;
    setErrorHandler(handler: (error: MinigameError) => void): void;
  }

  interface MenuShowOptions {
    gradually?: boolean;
  }

  interface MenuHideOptions {
    gradually?: boolean;
  }

  interface PaymentShowOptions {
    params: PaymentParams;
    extra?: PaymentExtra;
  }

  interface ShowResult {
    res: string;
    size?: {
      width?: string;
      height?: string;
    };
  }

  interface LoginOptions {
    success?: (result: LoginResult) => void;
    fail?: (error: LoginError) => void;
  }

  interface LoginError {
    code: number;
    message: string;
    error: string;
  }

  interface LoginResult {
    code: number;
    message: string;
    data: {
      jwtToken: string;
      expiresIn: number;
      refreshToken: string;
    };
  }

  interface PaymentResult {
    order_no: string;        // 订单号
    openid: string;          // 用户ID
    order_no_hash: string;   // 订单哈希值
  }

  interface PaymentError extends Error {
    code: string;
    type: 'failed' | 'hide' | 'queryChannelsFailed';
    data?: any;
    timestamp: number;
  }

  interface ProductsParams {
    game_openid: string;
    role_id: string;
    server_id?: string;
  }

  interface ProductItem {
    id: string;
    price: string;
    oldPrice: string;
    productIcon: string;
    baseCoinsNum: number;
    sendCoinsNum: number;
    name: string;
    discount: string;
    extraList: any[];
    meta: any;
  }

  interface ProductsResult {
    products: ProductItem[];
  }

  function minigame(options: MinigameOptions): MinigameAPI;
}

6. 使用示例​

6.1 完整示例​

// 初始化 SDK
const minigameApi = midas.minigame({
  appid: '1460000904',
  region: 'us',
  language: 'en',
  sandbox: 1,
  shopcode: 'xxxinapp',
  menu: {
    isWithPcHeader: true
  },
  payment: {
    openid: '1018553529511732'
  },
  login: {
    debug: true,
    timeout: 30000
  }
});

// 监听事件
minigameApi.on('sdk:loaded', (modules) => {
  console.log('SDK加载完成:', modules);
  
  // 获取模块实例以便直接访问
  const menuModule = minigameApi.getModule('menu');
  const paymentModule = minigameApi.getModule('payment');
  const loginModule = minigameApi.getModule('login');
  
  console.log('菜单模块:', menuModule);
  console.log('支付模块:', paymentModule);
  console.log('登录模块:', loginModule);
});

minigameApi.on('payment:success', (data) => {
  console.log('支付成功:', data);
  // 隐藏支付页面
  minigameApi.hidePayment();
});

minigameApi.on('login:success', (data) => {
  console.log('登录成功:', data);
  // 显示游戏菜单
  minigameApi.showMenu({
    gradually: true
  });
});

minigameApi.on('login:statusChanged', (status) => {
  console.log('登录状态变化:', status);
});

minigameApi.on('products:success', (data) => {
  console.log('商品数据加载成功:', data);
  data.products.forEach(product => {
    console.log(`商品: ${product.name}, 价格: ${product.price}`);
  });
});

minigameApi.on('products:failed', (error) => {
  console.log('商品数据加载失败:', error);
});

// 用户登录 - 回调方式
minigameApi.login({
  success: function(result) {
    console.log('登录成功:', result);
  },
  fail: function(error) {
    console.log('登录失败:', error);
  }
});

// 用户登录 - Promise 方式
minigameApi.login()
  .then(result => {
    console.log('登录成功:', result);
    // 登录成功后显示游戏菜单
    return minigameApi.showMenu({ gradually: true });
  })
  .catch(error => {
    console.log('登录失败:', error);
  });

// 显示游戏菜单
minigameApi.showMenu({
  gradually: true
});

// 显示支付页面 - Promise 方式（推荐）
minigameApi.showPayment({
  params: {
    game_openid: '1018553529511732',
    role_id: '1555629938',
    product_id: 'coins_01-midasbuy'
  },
  extra: {
    hideResultPage: true
  }
})
.then(result => {
  console.log('支付成功:', result);
  // result 包含: { order_no, openid, order_no_hash }
})
.catch(error => {
  console.log('支付错误:', error.type, error.message);
  
  // 处理特定错误类型
  if (error.type === 'queryChannelsFailed') {
    console.log('请检查网络连接');
  } else if (error.type === 'hide') {
    console.log('用户取消了支付');
  }
});

// 获取商品数据
minigameApi.getProductsData({
  game_openid: '1018553529511732',
  role_id: '1555629938',
  server_id: 'server_001'
})
.then(result => {
  console.log('商品数据加载成功:', result);
  result.products.forEach(product => {
    console.log(`商品: ${product.name} - ${product.price} (${product.baseCoinsNum}+${product.sendCoinsNum} UC)`);
  });
})
.catch(error => {
  console.log('商品数据加载失败:', error);
});

7. 最佳实践​

7.1 错误处理​

minigameApi.setErrorHandler((error) => {
  // 上报错误到监控系统
  reportError(error);
  
  // 用户友好的错误提示
  if (error.code === 'PAYMENT_FAILED') {
    showToast('支付失败，请稍后重试');
  }
});

7.2 基于 Promise 的支付流程​

// 现代化的 async/await 支付流程
class PaymentManager {
  constructor(minigameApi) {
    this.minigameApi = minigameApi;
  }

  async processPayment(productId, userId, roleId) {
    try {
      console.log('开始支付流程...');
      
      const result = await this.minigameApi.showPayment({
        params: {
          game_openid: userId,
          role_id: roleId,
          product_id: productId,
          server_id: 'server_001'
        },
        extra: {
          hideResultPage: true
        }
      });

      // 支付成功
      console.log('支付完成:', result);
      this.handlePaymentSuccess(result);
      return result;

    } catch (error) {
      console.log('支付出现错误:', error);
      this.handlePaymentError(error);
      throw error;
    }
  }

  handlePaymentSuccess(result) {
    // 更新游戏状态，解锁内容等
    console.log(`订单 ${result.order_no} 已完成，用户 ${result.openid}`);
    
    // 显示成功消息
    this.showNotification('支付成功！您的购买内容现已可用。');
  }

  handlePaymentError(error) {
    switch (error.type) {
      case 'failed':
        this.showNotification('支付失败，请重试。');
        this.trackEvent('payment_failed', error.data);
        break;
      
      case 'hide':
        this.showNotification('支付已取消。');
        this.trackEvent('payment_cancelled');
        break;
      
      case 'queryChannelsFailed':
        this.showNotification('无法加载支付选项，请检查网络连接。');
        this.trackEvent('payment_channels_failed', error.data);
        break;
    }
  }

  showNotification(message) {
    // 显示用户友好的通知
    console.log(`[通知] ${message}`);
  }

  trackEvent(eventName, data = null) {
    // 记录分析事件
    console.log(`[分析] ${eventName}`, data);
  }
}

7.3 基于 Promise 的登录流程​

// 现代化的 async/await 登录流程
class GameManager {
  constructor() {
    this.minigameApi = midas.minigame(config);
    this.setupEventListeners();
  }

  async initializeGame() {
    try {
      // 等待 SDK 加载完成
      await this.waitForSDKLoad();
      
      // 尝试登录
      const loginResult = await this.minigameApi.login();
      console.log('用户已登录:', loginResult.data.jwtToken);
      
      // 登录成功后显示游戏菜单
      await this.minigameApi.showMenu({ gradually: true });
      
    } catch (error) {
      console.error('游戏初始化失败:', error);
      this.handleInitError(error);
    }
  }

  waitForSDKLoad() {
    return new Promise((resolve) => {
      this.minigameApi.on('sdk:loaded', resolve);
    });
  }

  handleInitError(error) {
    // 处理初始化错误
    if (error.code === 'MODULE_NOT_LOADED') {
      console.error('SDK 模块未正确加载');
    }
  }
}

7.4 事件管理​

// 使用事件委托模式
class GameManager {
  constructor() {
    this.minigameApi = midas.minigame(config);
    this.setupEventListeners();
  }

  setupEventListeners() {
    this.minigameApi.on('payment:success', this.handlePaymentSuccess.bind(this));
    this.minigameApi.on('menu:show', this.handleMenuShow.bind(this));
  }

  handlePaymentSuccess(data) {
    // 处理支付成功
    this.updateGameState(data);
  }

  handleMenuShow(data) {
    // 处理游戏菜单显示
    this.trackEvent('menu_show', data);
  }
}