社交

FRVR.social 管理玩家的好友,并提供渠道原生的分享入口(分享面板、邀请选择器、更新通知)。

它分三层:

FRVR.social —— FRVR 自己的好友图,与服务器同步。跨渠道、持久化。
FRVR.social.platform —— 直接访问渠道的社交 UI(Facebook 好友选择器、iOS 分享面板等)。
FRVR.social.live —— WebSocket 连接,用于好友间的实时在线状态与游戏邀请。

FRVR 好友

需要 auth。

// 上传渠道好友列表,FRVR 会做匹配并注册
await FRVR.social.syncFriends();

// 读取已同步的列表(在所有渠道上结构一致)
const { friends } = await FRVR.social.getAllFriends();

// 通过 FRVR id 或渠道自身的 id 查询
const a = await FRVR.social.getFriendByFRVRID('frvr_123');
const b = await FRVR.social.getFriendByChannelId('fb_4567');

// 手动增删(例如通过邀请码)
await FRVR.social.addFriend(targetFrvrId);
await FRVR.social.removeFriend(targetFrvrId);

默认配置会在登录时自动同步好友:

FRVR.config.social = {
  syncFriendsOnLogin: true,
};

平台入口

如果宿主平台有原生的分享面板或邀请流程,就走 platform。每个调用在用户完成(或取消)交互后 resolve。

接按钮之前永远先看 getSupportedAPIs() —— 不是每个渠道都提供每个入口。

const supported = FRVR.social.platform.getSupportedAPIs();
// → ['shareMessage', 'invite', …] —— 不支持的就别显示对应 UI

if (FRVR.social.platform.isSupportedAPI('invite')) {
  // …
}

分享消息

发布到用户的动态 / 故事 / 分享面板,具体行为视渠道而定。

await FRVR.social.platform.shareMessage({
  image:    '/share/score.png',     // BASE64、JPEG 或 PNG
  text:     'I hit 10,000 points!',
  headline: 'New high score',
  cta:      'Beat my score',
  entryPointData: { from: 'share', score: 10000 },
});

字段	类型	必填	说明
`image`	`string`	是	图片 data URL 或托管 URL(BASE64 / JPEG / PNG)。
`text`	`string`	是	正文 / 描述文字。
`headline`	`string`	否	正文上方的简短标题(渠道支持时)。
`cta`	`string`	否	行动号召按钮文案。
`entryPointData`	`object`	否	接收方打开分享时,通过入口点拿到的任意 payload。

邀请好友

打开渠道的好友选择器,让玩家把具体联系人邀请进游戏。

if (await FRVR.social.platform.canInvite()) {
  await FRVR.social.platform.invite({
    image:    '/invite/banner.png',
    text:     'Come play with me!',
    headline: 'Join my game',
    cta:      'Play now',
    entryPointData: { from: 'invite', lobbyId: 'lobby_42' },
  });
}

字段	类型	必填	说明
`image`	`string`	是	图片 data URL 或托管 URL(BASE64 / JPEG / PNG)。
`text`	`string`	是	与图片一同展示的文案。
`headline`	`string`	否	正文上方的简短标题(渠道支持时)。
`cta`	`string`	否	行动号召按钮文案。
`entryPointData`	`object`	否	接收方加入时,通过入口点拿到的 payload。

canInvite() 在不支持邀请的渠道、或宿主当前上下文不允许邀请的情况下返回 false —— 用它来控制 UI 的显隐。

平台更新

把控制权暂时交给平台,让它通过模板下发一条更新(Facebook context update、Snapchat sticker、Discord activity 等)。模板存放在 @frvr-social/defaultTemplatesConfig,需要把对应渠道的配置拷进游戏目录后才能用。

await FRVR.social.platform.sendUpdate({
  template:       'JOIN_PLAYER',
  image:          '/update/lobby.png',
  bitmojiVariant: 'HAPPY',                    // 仅 Snapchat
  entryPointData: { lobbyId: 'lobby_42' },
});

字段	类型	说明
`template`	`string`	预定义模板名(如 `'JOIN_PLAYER'`)。
`image`	`string`	图片 data URL 或托管 URL(BASE64 / JPEG / PNG)。
`bitmojiVariant`	`string`	Snapchat bitmoji 表情 —— `'HAPPY'`、`'WINK'`、`'HEARTEYES'` 等,完整列表见 SDK 类型。
`entryPointData`	`object`	接收方打开更新时,通过入口点拿到的 payload。
`override`	`object`	各渠道的原始 payload(`snapchat`、`facebookInstant`、`facebookRooms`、`discord`),用来替换模板字段。

好友与上下文

const friends = await FRVR.social.platform.getFriends();
// → Friend[]:{ id, name, nickname?, image, channel }

// 玩家在宿主上当前所处的位置(FB context、Snap chat、Discord activity ……)
const ctxId      = await FRVR.social.platform.getContextId();
const ctxData    = await FRVR.social.platform.getContextData();
const ctxPlayers = await FRVR.social.platform.getContextPlayers();

getFriends() 返回当前渠道上玩过本游戏的好友 —— 尽力而为,具体取决于各渠道的策略。需要跨渠道的 FRVR 图谱时,改用 FRVR.social.getAllFriends()。

在线试一下

实时更新

FRVR.social.live 会开一个 WebSocket,让你能实时响应好友上线、互发游戏邀请、广播自己的状态。需要 auth。

const { live } = FRVR.social;

live.connect();

live.on(live.SocialEvents.onConnect, ({ data }) => {
  // data.friends: Status[] —— 每个好友的当前在线快照
});

live.on(live.SocialEvents.onFriendStatusUpdated, ({ data }) => {
  // data: { userId, gameId, presence: 'online' | 'offline', metadata }
  if (data.presence === 'online') toast(`${data.userId} is online`);
});

live.on(live.SocialEvents.onGameInvite, ({ data }) => {
  // data: { recipientId, gameId, lobbyId }
  showInvitePrompt(data.lobbyId);
});

live.on(live.SocialEvents.onError, ({ data }) => {
  console.warn('social live error', data.message);
});

发送

// 告诉好友你在干什么 —— 会出现在他们的 onFriendStatusUpdated 中
live.updateStatus({ inLobby: 'lobby_42', mode: 'co-op' });

// 直接邀请某个好友
live.sendGameInvite('frvr_123', 'lobby_42', { mode: 'co-op' });

快照

const status = live.getFriendsStatus();   // Status[] —— 每个好友最近一次的在线状态

断开

live.close();

登出时连接会自动关闭。

API 概要

`FRVR.social` —— 好友图

方法	用途
`syncFriends()`	把渠道好友列表推到 FRVR;匹配并把好友登记为 FRVR id。
`getAllFriends()`	读取已同步的跨渠道好友列表。
`getFriendByFRVRID(frvrId)`	通过 FRVR id 查找已同步好友。
`getFriendByChannelId(channelId)`	通过渠道原生 id 查找已同步好友。
`addFriend(frvrId)` / `removeFriend(frvrId)`	手动改动好友图。

`FRVR.social.platform` —— 渠道 UI

方法	用途
`shareMessage(config)`	打开渠道的分享面板,带图片 + 文案。
`invite(config)` / `canInvite()`	打开渠道好友邀请选择器,先看支持再调。
`sendUpdate(config)`	模板化的平台更新(FB context update、Snap sticker ……)。
`getFriends()`	当前渠道上玩本游戏的好友。
`getContextId()` / `getContextData()` / `getContextPlayers()`	当前宿主上下文(对话、房间、派对)。
`getSupportedAPIs()` / `isSupportedAPI(api)`	能力检测 —— 据此控制 UI 显隐。

`FRVR.social.live` —— 实时

方法 / 事件	用途
`connect()` / `close()`	打开或关闭 WebSocket。auth 刷新时会自动重连。
`on(event, cb)`	订阅 `onConnect`、`onFriendStatusUpdated`、`onGameInvite`、`onError`。
`updateStatus(metadata)`	把自己的状态 metadata 广播给好友。
`sendGameInvite(recipientId, lobbyId, metadata?)`	给某个好友推送一条 `onGameInvite`。
`getFriendsStatus()`	每个好友最近一次的在线状态快照。

社交