# Chia sẻ, bạn bè và lời mời trong game PlayDrop

Chia sẻ game kèm ảnh hoặc đoạn video, đọc dữ liệu khởi chạy, chọn bạn bè, gửi thẻ mời và thẻ thách đấu trong PlayDrop Chat, và đề xuất game khác.

Source: https://www.playdrop.ai/vi/create/learn/social

PlayDrop lo bảng chia sẻ, danh sách bạn bè và chat; game của bạn chỉ cần yêu cầu chúng vào đúng lúc. Người chơi rủ bạn bè, và bạn bè vào thẳng game của bạn.

## Chia sẻ game

Gọi `sdk.host.share()` từ một lần chạm hoặc nhấp chuột. Lệnh này chia sẻ trang công khai của game kèm văn bản, một hình ảnh hoặc một đoạn video ngắn tùy chọn, và một dữ liệu khởi chạy (payload) tùy chọn.

```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`: một Blob GIF, JPEG, PNG hoặc WebP tối đa 8 MiB. Host không đính kèm được hình ảnh sẽ chỉ chia sẻ liên kết.
- `video`: một Blob MP4 dài tối đa 15 giây và 20.000.000 byte, thay cho hình ảnh. H.264/AAC ở 1080p với tỷ lệ 16:9, 9:16 hoặc 1:1 cho kết quả tốt nhất. Host không hỗ trợ video sẽ từ chối với `host_share_video_unsupported` thay vì chia sẻ một liên kết thông thường.
- Hãy chuẩn bị Blob trước lần chạm; tạo nó sau lần chạm có thể làm mất quyền chia sẻ của trình duyệt.
- Bạn không thể chia sẻ URL tùy chỉnh hay tệp khác. Liên kết luôn là trang của game.

Lỗi hình ảnh gồm `invalid_host_share_image`, `host_share_image_type` và `host_share_image_too_large`.

## Đọc dữ liệu khởi chạy

`payload` dài tối đa 256 ký tự base64url. Người chơi mở liên kết được chia sẻ sẽ khởi động game với `sdk.host.launchPayload` được đặt bằng giá trị đó, hoặc `null`. Hãy coi nó là đầu vào không đáng tin cậy: kiểm tra tính hợp lệ, và kiểm tra trên máy chủ rằng người chơi được phép vào phòng mà nó nêu tên. Không bao giờ đặt thông tin xác thực trong đó.

## Chọn bạn bè và gửi thẻ game

`sdk.social.selectFriends({ max })` mở bộ chọn bạn bè của PlayDrop (từ 1 đến 10, mặc định 1) và chỉ trả về những người bạn mà người chơi đã chọn, hoặc `[]` nếu họ hủy. Sau đó hãy gửi một thẻ hiện trong 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` là `invite`, `request`, `gift`, `challenge` hoặc `turn`.
- `title` tối đa 80 ký tự và `subtitle` tối đa 160 ký tự.
- `expiresInSeconds` từ 60 giây đến 30 ngày (mặc định).
- `clientMessageId` giúp thử lại an toàn: dùng lại giá trị này sẽ trả về tin nhắn ban đầu.
- Bạn có thể nhắn cho những người bạn mà người chơi đã chọn, bạn bè đang chơi game này và những người chơi mà họ đã từng trao đổi tin nhắn game. Không thể nhắn cho người lạ gặp qua ghép trận.

Đọc thẻ nhận được bằng `getMessages({ limit })`, cũ nhất trước, rồi đánh dấu từng thẻ đã xử lý bằng `consumeMessage(message.id)`. Người gửi là `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);
}
```

Tiếp tục với `cursor: page.nextCursor` cho đến khi giá trị này là `null`.

## Bạn bè đang chơi game này

`sdk.social.listGameFriends()` trả về những người bạn có phiên chơi gần đây trong game này: một danh sách phù hợp cho các nút "chơi cùng". Nó không để lộ toàn bộ danh sách bạn bè hay trạng thái trực tuyến. `openProfile(userId)` mở hồ sơ của một người chơi và `openChat({ recipientUserId, draftMessage })` mở Chat với một bản nháp có thể chỉnh sửa mà người chơi tự gửi.

Người chơi mới đến từ lời mời của một người bạn có thể có `sdk.host.launchFriend`. Hãy đề nghị chơi cùng người bạn đó và xác nhận bằng `selectFriends({ max: 1 })`; không bao giờ tự động bắt đầu bất cứ điều gì.

## Đề xuất game khác

Vào một điểm nghỉ tự nhiên, như khi kết thúc ván, `sdk.host.showGames({ games: ["@creator/name"] })` hiển thị thẻ PlayDrop cho một đến ba game công khai khác và tạm dừng game của bạn. Lệnh này trả về `played` (khi đó PlayDrop chuyển game) hoặc `dismissed`. `sdk.host.preloadGame(ref)` gợi ý game mà người chơi có thể mở tiếp theo.

## Yêu cầu

Các lệnh gọi chia sẻ và xã hội cần một [gói](https://www.playdrop.ai/vi/create/learn/packaging) có dùng SDK. Tính năng bạn bè cần người chơi đã đăng nhập. Cửa sổ do host quản lý sẽ tạm dừng game; hãy xử lý [tạm dừng và tiếp tục](https://www.playdrop.ai/vi/create/learn/lifecycle).

## Hướng dẫn liên quan

- [Nhóm chơi trực tuyến và thoại](https://www.playdrop.ai/vi/create/learn/online-party): Cho bạn bè chơi cùng nhau trực tuyến: khai báo quy mô nhóm chơi, mở cửa sổ nhóm chơi của PlayDrop, vào phòng đã giữ chỗ bằng sdk.multiplayer.join, điều khiển thoại phòng.
- [Chế độ hiển thị và tiếp cận](https://www.playdrop.ai/vi/create/learn/distribution): Chọn ai mở được game PlayDrop, cách hoạt động của cài đặt mặc định và việc xuất bản phiên bản, cùng cách Boost, Trao đổi lượt chơi, Instant, tìm kiếm đem về người chơi.
- [Bảng xếp hạng](https://www.playdrop.ai/vi/create/learn/leaderboards): Khai báo bảng xếp hạng trong catalogue.json, gửi điểm bằng sdk.leaderboards, hiển thị hạng đầu và người chơi xung quanh. Loại điểm, giới hạn và quy tắc cập nhật.