Meta Instant Games SDK 接入指南

本文档旨在帮助开发者快速接入 Meta Instant Games 平台,实现社交分享、排位赛、快捷方式等功能。

快速开始

前置条件

  1. 已在 Meta 开发者平台创建 Instant Games 应用

  2. 已完成基础 Minigame.com SDK的接入

SDK 初始化

// 确保 minigame SDK 已正确加载
if (typeof minigame !== 'undefined') {
  console.log('SDK 已就绪');
}

社区功能

社区功能允许在游戏界面上展示 Meta 主页或群组的预览卡片,帮助提升用户粘性和社区互动。

关注官方主页

在游戏界面上方显示 Meta 主页预览卡片,包含页面头像、点赞数和置顶帖子。
image.png

使用流程

async function showOfficialPage() {
  try {
    // 步骤1: 检查功能是否可用
    const canFollow = await minigame.community.canFollowOfficialPageAsync();

    if (!canFollow) {
      console.log('当前环境不支持关注主页功能');
      return;
    }

    // 步骤2: 显示主页预览卡片
    await minigame.community.followOfficialPageAsync();
    console.log('主页卡片已展示');

  } catch (error) {
    console.error('关注主页失败:', error);
  }
}

API 说明

方法返回值说明
canFollowOfficialPageAsync()Promise<boolean>检查当前环境是否支持关注主页功能
followOfficialPageAsync()Promise<void>渲染并显示主页预览卡片

加入官方群组

显示官方 Meta 群组预览,用户可以水平滚动浏览群组内容。
image.png

使用流程

async function showOfficialGroup() {
  try {
    // 步骤1: 检查功能是否可用
    const canJoin = await minigame.community.canJoinOfficialGroupAsync();

    if (!canJoin) {
      console.log('当前环境不支持加入群组功能');
      return;
    }

    // 步骤2: 显示群组预览
    await minigame.community.joinOfficialGroupAsync();
    console.log('群组预览已展示');

  } catch (error) {
    console.error('加入群组失败:', error);
  }
}

API 说明

方法返回值说明
canJoinOfficialGroupAsync()Promise<boolean>检查当前环境是否支持加入群组功能
joinOfficialGroupAsync()Promise<void>渲染并显示群组预览卡片

智能助手订阅

允许玩家订阅游戏的 Messenger 智能助手,便于推送游戏通知、活动提醒等消息。

使用流程

async function subscribeBot() {
  try {
    // 步骤1: 检查是否可以订阅
    const canSubscribe = await minigame.player.canSubscribeBotAsync();

    if (!canSubscribe) {
      console.log('当前玩家无法订阅智能助手');
      return;
    }

    // 步骤2: 请求用户订阅
    await minigame.player.subscribeBotAsync();
    console.log('订阅成功');

  } catch (error) {
    console.error('订阅失败:', error);
  }
}

API 说明

方法返回值说明
canSubscribeBotAsync()Promise<boolean>检查玩家是否可以订阅智能助手
subscribeBotAsync()Promise<void>发起订阅请求,显示订阅确认对话框

分享与邀请

分享功能

将游戏内容分享给好友或群组,支持携带自定义数据。

参数说明

参数类型必填说明
imagestringBase64 编码的分享图片
textstring分享文案
dataobject自定义数据,接收方在游戏启动后,通过 minigame.getEntryPointData() 获取
switchContextboolean分享后是否切换到目标上下文
intentstring分享意图,可选值见下表
shareDestinationstring[]指定分享目标

Intent 可选值

使用场景
INVITE邀请好友加入游戏
REQUEST向好友请求帮助
CHALLENGE向好友发起挑战
SHARE普通分享

完整示例

async function shareToFriends() {
  try {
    // 准备分享图片(Base64 格式)
    const base64Image = await generateShareImage();

    await minigame.shareAsync({
      image: base64Image,
      text: '我在游戏中获得了 1000 分,快来挑战我吧!',
      data: {
        score: 1000,
        level: 5,
        timestamp: Date.now()
      },
      switchContext: false,
      intent: 'SHARE'
    });

    console.log('分享成功');

  } catch (error) {
    // 用户取消分享或分享失败
    console.error('分享失败:', error);
  }
}

邀请功能

向好友发送游戏邀请,支持多语言文案。

参数说明

参数类型必填说明
imagestringBase64 编码的邀请图片
text`string | LocalizableContent`邀请文案,支持多语言
dataobject附加到分享的数据块。从分享启动的所有游戏会话都可以通minigame.getEntryPointData()访问此数据块
filtersArray好友筛选条件
sectionsArray分区配置
dialogTitle`string | LocalizableContent`对话框标题

多语言文案示例

async function inviteFriends() {
  try {
    const base64Image = await generateInviteImage();

    await minigame.inviteAsync({
      image: base64Image,
      text: {
        default: 'Join me in this awesome game!',
        localizations: {
          en_US: 'Join me in this awesome game!',
          zh_CN: '快来和我一起玩这个游戏吧!',
          es_LA: '¡Únete a mí en este increíble juego!'
        }
      },
      data: {
        inviterId: 'player123',
        reward: 'bonus_coins'
      },
      dialogTitle: {
        default: 'Invite Friends',
        localizations: {
          en_US: 'Invite Friends',
          zh_CN: '邀请好友',
          es_LA: 'Invitar Amigos'
        }
      }
    });

    console.log('邀请发送成功');

  } catch (error) {
    console.error('邀请失败:', error);
  }
}

桌面快捷方式

允许用户将游戏添加到设备桌面,便于快速启动。

使用流程

async function createDesktopShortcut() {
  try {
    // 步骤1: 检查是否可以创建快捷方式
    const canCreate = await minigame.canCreateShortcutAsync();

    if (!canCreate) {
      console.log('当前环境不支持创建桌面快捷方式');
      return;
    }

    // 步骤2: 请求创建快捷方式
    await minigame.createShortcutAsync();
    console.log('快捷方式创建成功');

  } catch (error) {
    // 用户拒绝或创建失败
    console.error('创建快捷方式失败:', error);
  }
}

API 说明

方法返回值说明
canCreateShortcutAsync()Promise<boolean>检查当前环境是否支持创建快捷方式
createShortcutAsync()Promise<void>请求用户允许创建桌面快捷方式

⚠️ 注意: 建议在合适的时机(如游戏暂停、关卡结束)调用此功能,避免打断用户体验。


排位赛系统

排位赛(Tournament)是 Meta Instant Games 的核心社交功能之一,允许玩家创建和参与竞技比赛。

创建排位赛

参数说明

参数类型必填说明
initialScorenumber创建者的初始分数
dataobject附加到更新的数据块。从更新启动的所有游戏会话都将能够从锦标赛的有效负载上访问此数据块若,可以通过minigame.getEntryPointData()来获取data对象。当字符串化时,必须小于或等于 1000 个字符。
configTournamentConfig排位赛配置

TournamentConfig 配置项

字段类型必填说明
titlestring排位赛名称
sortOrderstring排序方式:HIGHER_IS_BETTERLOWER_IS_BETTER
scoreFormatstring分数格式:NUMERIC(数字)或 TIME(时间)
endTimenumber结束时间(Unix 时间戳,单位:秒)
imagestring与排位赛相关联并包含在分享排位赛中的可选 base64 编码图像。

完整示例

async function createTournament() {
  try {
    // 创建排位赛前,若当前上下文ID不为空,需要先切换到 SOLO 模式,
    const contextId = minigame.context.getID();
    if (contextId != null) {
		await minigame.context.switchAsync('SOLO', true);
    }    

    // 计算结束时间(7天后)
    const endTime = Math.floor(Date.now() / 1000) + 7 * 24 * 60 * 60;

    const tournament = await minigame.tournament.createAsync({
      initialScore: 100,
      data: {
        tournamentLevel: 'hard',
        gameMode: 'challenge'
      },
      config: {
        title: '周末挑战赛',
        sortOrder: 'HIGHER_IS_BETTER',
        scoreFormat: 'NUMERIC',
        endTime: endTime
      }
    });

    console.log('排位赛创建成功:', tournament.getID());
    return tournament;

  } catch (error) {
    console.error('创建排位赛失败:', error);
  }
}

获取排位赛

获取当前排位赛

async function getCurrentTournament() {
  try {
    const tournament = await minigame.getTournamentAsync();

    if (tournament) {
      console.log('当前排位赛ID:', tournament.getID());
      console.log('排位赛名称:', tournament.getTitle());
      console.log('结束时间:', new Date(tournament.getEndTime() * 1000));
    } else {
      console.log('当前没有进行中的排位赛');
    }

    return tournament;

  } catch (error) {
    console.error('获取排位赛失败:', error);
  }
}

获取可加入的排位赛列表

async function getAvailableTournaments() {
  try {
    const tournaments = await minigame.tournament.getTournamentsAsync();

    console.log(`找到 ${tournaments.length} 个可加入的排位赛`);

    tournaments.forEach((t, index) => {
      console.log(`${index + 1}. ${t.getTitle()} (ID: ${t.getID()})`);
    });

    return tournaments;

  } catch (error) {
    console.error('获取排位赛列表失败:', error);
  }
}

切换上下文

上下文(Context)是排位赛的运行环境,切换上下文可以进入或退出排位赛。

// 切换到 SOLO 模式(创建新排位赛前需要)
const contextId = minigame.context.getID();
if (contextId != null) {
	await minigame.context.switchAsync('SOLO', true);
}    

// 切换到指定排位赛
await minigame.context.switchAsync(tournament.getContextID());

分享排位赛

将排位赛分享给好友,邀请他们加入比赛。

参数说明

参数类型必填说明
scorenumber代表玩家最新分数的可选整数值
dataobject附加到更新的数据块。从更新启动的所有游戏会话都将能够从锦标赛的有效负载上访问此数据块若,可以通过minigame.getEntryPointData()来获取data对象。当字符串化时,必须小于或等于 1000 个字符。
async function shareTournament(score) {
  try {
    await minigame.tournament.shareAsync({
      score: score,
      data: {
        sharedAt: Date.now(),
        message: '来挑战我的分数吧!'
      }
    });

    console.log('排位赛分享成功');

  } catch (error) {
    console.error('分享排位赛失败:', error);
  }
}

Tournament 对象

Tournament 对象包含以下方法:

方法返回值说明
getID()string获取排位赛唯一标识
getContextID()string获取排位赛上下文 ID
getEndTime()number获取结束时间(Unix 时间戳)
getTitle()string获取排位赛名称
getPayload()object获取自定义数据
getTournamentType()string获取排位赛类型

常见问题

Q: 为什么 canFollowOfficialPageAsync() 返回 false?

A: 可能原因:

  1. 游戏未关联 Facebook 主页

  2. 当前平台不支持该功能(如某些浏览器环境)

  3. 用户已经关注了主页

Q: 分享图片有什么要求?

A: 分享图片需要满足:

  • 格式:Base64 编码的图片数据

  • 推荐尺寸:1200 x 628 像素

  • 格式类型:PNG 或 JPEG

  • 大小限制:不超过 2MB

Q: 排位赛创建失败怎么办?

A: 检查以下几点:

  1. 判断当前是否已处于排位赛上下文,通过minigame.context.getID()不为空来判断,不为空则需要先切换到 SOLO 模式

  2. endTime 必须是未来的时间戳

  3. sortOrderscoreFormat 必须是有效值

Q: 如何测试这些功能?

A:

  1. 使用 Meta 开发者模式进行测试

  2. 确保测试账号已添加为游戏管理员或测试用户

  3. 在 Meta Gaming 平台上预览游戏

商务对接
商务对接
公众号
公众号