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

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

Source: https://www.playdrop.ai/zh-hant/create/learn/social

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

## 分享遊戲

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

```js
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 中的卡片：

```js
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`。

```js
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.host.showGames({ games: ["@creator/name"] })` 會顯示一到三款其他公開遊戲的 PlayDrop 卡片，並暫停你的遊戲。它會以 `played`（接著 PlayDrop 會切換遊戲）或 `dismissed` 完成。`sdk.host.preloadGame(ref)` 會提示玩家接下來可能開啟的遊戲。

## 需求

分享與社群呼叫需要使用 SDK 的[套件](https://www.playdrop.ai/zh-hant/create/learn/packaging)。好友功能需要已登入的玩家。主機端擁有的視窗會暫停遊戲；請處理[暫停與恢復](https://www.playdrop.ai/zh-hant/create/learn/lifecycle)。

## 相關指南

- [線上派對與語音](https://www.playdrop.ai/zh-hant/create/learn/online-party): 讓朋友一起線上玩你的遊戲：宣告派對人數、開啟 PlayDrop 的派對視窗、用 sdk.multiplayer.join 加入預留的房間，並控制房間語音。
- [可見性與觸及](https://www.playdrop.ai/zh-hant/create/learn/distribution): 選擇誰能開啟 PlayDrop 遊戲，了解帳號預設值與版本發布如何運作，以及 Boost、互玩、即玩和搜尋如何帶來新玩家。
- [排行榜](https://www.playdrop.ai/zh-hant/create/learn/leaderboards): 在 catalogue.json 中宣告排行榜，用 sdk.leaderboards 提交分數，並顯示前幾名與玩家周邊的排名。包含分數類型、限制與更新規則。