本文档旨在帮助开发者快速接入 Meta Instant Games 平台,实现社交分享、排位赛、快捷方式等功能。
快速开始
前置条件
已在 Meta 开发者平台创建 Instant Games 应用
已完成基础 Minigame.com SDK的接入
SDK 初始化
if (typeof minigame !== 'undefined') {
console.log('SDK 已就绪');
}
社区功能
社区功能允许在游戏界面上展示 Meta 主页或群组的预览卡片,帮助提升用户粘性和社区互动。
关注官方主页
在游戏界面上方显示 Meta 主页预览卡片,包含页面头像、点赞数和置顶帖子。

使用流程
async function showOfficialPage() {
try {
const canFollow = await minigame.community.canFollowOfficialPageAsync();
if (!canFollow) {
console.log('当前环境不支持关注主页功能');
return;
}
await minigame.community.followOfficialPageAsync();
console.log('主页卡片已展示');
} catch (error) {
console.error('关注主页失败:', error);
}
}
API 说明
| 方法 | 返回值 | 说明 |
|---|
canFollowOfficialPageAsync() | Promise<boolean> | 检查当前环境是否支持关注主页功能 |
followOfficialPageAsync() | Promise<void> | 渲染并显示主页预览卡片 |
加入官方群组
显示官方 Meta 群组预览,用户可以水平滚动浏览群组内容。

使用流程
async function showOfficialGroup() {
try {
const canJoin = await minigame.community.canJoinOfficialGroupAsync();
if (!canJoin) {
console.log('当前环境不支持加入群组功能');
return;
}
await minigame.community.joinOfficialGroupAsync();
console.log('群组预览已展示');
} catch (error) {
console.error('加入群组失败:', error);
}
}
API 说明
| 方法 | 返回值 | 说明 |
|---|
canJoinOfficialGroupAsync() | Promise<boolean> | 检查当前环境是否支持加入群组功能 |
joinOfficialGroupAsync() | Promise<void> | 渲染并显示群组预览卡片 |
智能助手订阅
允许玩家订阅游戏的 Messenger 智能助手,便于推送游戏通知、活动提醒等消息。
使用流程
async function subscribeBot() {
try {
const canSubscribe = await minigame.player.canSubscribeBotAsync();
if (!canSubscribe) {
console.log('当前玩家无法订阅智能助手');
return;
}
await minigame.player.subscribeBotAsync();
console.log('订阅成功');
} catch (error) {
console.error('订阅失败:', error);
}
}
API 说明
| 方法 | 返回值 | 说明 |
|---|
canSubscribeBotAsync() | Promise<boolean> | 检查玩家是否可以订阅智能助手 |
subscribeBotAsync() | Promise<void> | 发起订阅请求,显示订阅确认对话框 |
分享与邀请
分享功能
将游戏内容分享给好友或群组,支持携带自定义数据。
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|
image | string | ✅ | Base64 编码的分享图片 |
text | string | ✅ | 分享文案 |
data | object | ❌ | 自定义数据,接收方在游戏启动后,通过 minigame.getEntryPointData() 获取 |
switchContext | boolean | ❌ | 分享后是否切换到目标上下文 |
intent | string | ✅ | 分享意图,可选值见下表 |
shareDestination | string[] | ❌ | 指定分享目标 |
Intent 可选值
| 值 | 使用场景 |
|---|
INVITE | 邀请好友加入游戏 |
REQUEST | 向好友请求帮助 |
CHALLENGE | 向好友发起挑战 |
SHARE | 普通分享 |
完整示例
async function shareToFriends() {
try {
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);
}
}
邀请功能
向好友发送游戏邀请,支持多语言文案。
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|
image | string | ✅ | Base64 编码的邀请图片 |
text | `string | LocalizableContent` | ✅ | 邀请文案,支持多语言 |
data | object | ❌ | 附加到分享的数据块。从分享启动的所有游戏会话都可以通minigame.getEntryPointData()访问此数据块 |
filters | Array | ❌ | 好友筛选条件 |
sections | Array | ❌ | 分区配置 |
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 {
const canCreate = await minigame.canCreateShortcutAsync();
if (!canCreate) {
console.log('当前环境不支持创建桌面快捷方式');
return;
}
await minigame.createShortcutAsync();
console.log('快捷方式创建成功');
} catch (error) {
console.error('创建快捷方式失败:', error);
}
}
API 说明
| 方法 | 返回值 | 说明 |
|---|
canCreateShortcutAsync() | Promise<boolean> | 检查当前环境是否支持创建快捷方式 |
createShortcutAsync() | Promise<void> | 请求用户允许创建桌面快捷方式 |
⚠️ 注意: 建议在合适的时机(如游戏暂停、关卡结束)调用此功能,避免打断用户体验。
排位赛系统
排位赛(Tournament)是 Meta Instant Games 的核心社交功能之一,允许玩家创建和参与竞技比赛。
创建排位赛
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|
initialScore | number | ✅ | 创建者的初始分数 |
data | object | ❌ | 附加到更新的数据块。从更新启动的所有游戏会话都将能够从锦标赛的有效负载上访问此数据块若,可以通过minigame.getEntryPointData()来获取data对象。当字符串化时,必须小于或等于 1000 个字符。 |
config | TournamentConfig | ✅ | 排位赛配置 |
TournamentConfig 配置项
| 字段 | 类型 | 必填 | 说明 |
|---|
title | string | ✅ | 排位赛名称 |
sortOrder | string | ✅ | 排序方式:HIGHER_IS_BETTER 或 LOWER_IS_BETTER |
scoreFormat | string | ✅ | 分数格式:NUMERIC(数字)或 TIME(时间) |
endTime | number | ✅ | 结束时间(Unix 时间戳,单位:秒) |
| image | string | ❌ | 与排位赛相关联并包含在分享排位赛中的可选 base64 编码图像。 |
完整示例
async function createTournament() {
try {
const contextId = minigame.context.getID();
if (contextId != null) {
await minigame.context.switchAsync('SOLO', true);
}
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)是排位赛的运行环境,切换上下文可以进入或退出排位赛。
const contextId = minigame.context.getID();
if (contextId != null) {
await minigame.context.switchAsync('SOLO', true);
}
await minigame.context.switchAsync(tournament.getContextID());
分享排位赛
将排位赛分享给好友,邀请他们加入比赛。
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|
| score | number | ✅ | 代表玩家最新分数的可选整数值 |
data | object | ❌ | 附加到更新的数据块。从更新启动的所有游戏会话都将能够从锦标赛的有效负载上访问此数据块若,可以通过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: 可能原因:
游戏未关联 Facebook 主页
当前平台不支持该功能(如某些浏览器环境)
用户已经关注了主页
Q: 分享图片有什么要求?
A: 分享图片需要满足:
格式:Base64 编码的图片数据
推荐尺寸:1200 x 628 像素
格式类型:PNG 或 JPEG
大小限制:不超过 2MB
Q: 排位赛创建失败怎么办?
A: 检查以下几点:
判断当前是否已处于排位赛上下文,通过minigame.context.getID()不为空来判断,不为空则需要先切换到 SOLO 模式
endTime 必须是未来的时间戳
sortOrder 和 scoreFormat 必须是有效值
Q: 如何测试这些功能?
A:
使用 Meta 开发者模式进行测试
确保测试账号已添加为游戏管理员或测试用户
在 Meta Gaming 平台上预览游戏