一起玩

PlayDrop 遊戲中的分享、好友與邀請

附圖片或短片分享遊戲、讀取啟動酬載、挑選好友、在 PlayDrop Chat 中傳送邀請與挑戰卡片，並推薦其他遊戲。

PlayDrop 負責分享面板、好友清單和聊天；你的遊戲只要在適當的時機請求它們。玩家會帶來他們的朋友，而朋友會直接進入你的遊戲。

分享遊戲

在點按或點擊事件中呼叫 sdk.host.share()。它會分享遊戲的公開頁面，可選擇附上文字、圖片或短影片，以及啟動酬載。

shareButton.addEventListener("click", async () => {
  try {
    await sdk.host.share({ text: `I reached level ${level} in Moon Jump`, image: scoreCardBlob, payload: "level-7" });
  } catch (error) {
    console.warn("Share failed", error);
  }
});

image：最多 8 MiB 的 GIF、JPEG、PNG 或 WebP Blob。無法附加圖片的主機端只會分享連結。
video：最長 15 秒、最多 20,000,000 位元組的 MP4 Blob，用來取代圖片。以 16:9、9:16 或 1:1 的 1080p H.264/AAC 效果最好。不支援影片的主機端會以 host_share_video_unsupported 拒絕，而不是改為分享一般連結。
請在點按之前準備好 Blob；點按之後才產生，可能會失去瀏覽器的分享權限。
你無法分享自訂網址或其他檔案。連結永遠是遊戲的頁面。

圖片錯誤有 invalid_host_share_image、host_share_image_type 和 host_share_image_too_large。

讀取啟動酬載

payload 最多 256 個 base64url 字元。開啟分享連結的玩家啟動遊戲時，sdk.host.launchPayload 會設為該值，否則為 null。請將它視為不受信任的輸入：驗證它，並在你的伺服器上檢查玩家是否可以加入它指定的房間。絕不要在其中放入憑證。

挑選好友並傳送遊戲卡片

sdk.social.selectFriends({ max }) 會開啟 PlayDrop 的好友選擇器（1 到 10，預設為 1），只傳回玩家選擇的好友，若取消則傳回 []。接著傳送一張會出現在 PlayDrop Chat 中的卡片：

const [friend] = await sdk.social.selectFriends({ max: 1 });
if (friend) {
  await sdk.social.sendMessage({
    recipientUserId: friend.id,
    type: "challenge",
    title: "Beat my time: 42.3 s",
    subtitle: "Moon Jump, level 7",
    payload: "level-7",
    clientMessageId: `challenge-${runId}-${friend.id}`,
  });
}

type 為 invite、request、gift、challenge 或 turn。
title 最多 80 個字元，subtitle 最多 160 個字元。
expiresInSeconds 為 60 秒到 30 天（預設值）。
clientMessageId 讓重試變得安全：重複使用它會傳回原本的訊息。
你可以傳訊息給玩家選擇的好友、玩這款遊戲的好友，以及玩家已經互傳過遊戲訊息的玩家。無法傳訊息給在配對中遇到的陌生人。

用 getMessages({ limit }) 讀取收到的卡片（從最舊的開始），然後用 consumeMessage(message.id) 將每張標示為已處理。寄件者是 message.from.id。

const page = await sdk.social.getMessages({ limit: 20 });
for (const message of page.messages) {
  await applyCard(message.type, message.from.id, message.payload);
  await sdk.social.consumeMessage(message.id);
}

以 cursor: page.nextCursor 繼續讀取，直到它為 null。

玩這款遊戲的好友

sdk.social.listGameFriends() 會傳回最近在這款遊戲中有工作階段的好友：很適合用在「一起玩」按鈕上。它不會公開完整的好友清單或上線狀態。openProfile(userId) 會開啟玩家的個人檔案，openChat({ recipientUserId, draftMessage }) 則會開啟 Chat，並附上一則可編輯的草稿，由玩家自己傳送。

對於透過朋友而來的新玩家，sdk.host.launchFriend 可能已有值。請提議和對方一起玩，並用 selectFriends({ max: 1 }) 確認；絕不要自動開始任何事。

需求

分享與社群呼叫需要使用 SDK 的套件。好友功能需要已登入的玩家。主機端擁有的視窗會暫停遊戲；請處理暫停與恢復。

一起玩