# PlayDrop 게임의 공유, 친구, 초대

이미지나 클립과 함께 게임을 공유하고, 실행 페이로드를 읽고, 친구를 고르고, PlayDrop Chat으로 초대·도전 카드를 보내고, 다른 게임을 추천하세요.

Source: https://www.playdrop.ai/ko/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을 준비하세요. 탭한 뒤에 만들면 브라우저의 공유 권한을 잃을 수 있습니다.
- 사용자 지정 URL이나 다른 파일은 공유할 수 없습니다. 링크는 항상 게임 페이지입니다.

이미지 오류는 `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 })`는 플레이어가 직접 보낼 수 있는 수정 가능한 초안과 함께 채팅을 엽니다.

친구를 통해 들어온 새 플레이어에게는 `sdk.host.launchFriend`가 설정되어 있을 수 있습니다. 그 친구와 함께 플레이하자고 제안하고 `selectFriends({ max: 1 })`로 확인하세요. 아무것도 자동으로 시작하지 마세요.

## 다른 게임 추천하기

게임 오버 같은 자연스러운 휴식 지점에서 `sdk.host.showGames({ games: ["@creator/name"] })`를 호출하면 다른 공개 게임 1~3개의 PlayDrop 카드를 보여 주고 내 게임을 일시 정지합니다. 결과는 `played`(이후 PlayDrop이 게임을 전환) 또는 `dismissed`입니다. `sdk.host.preloadGame(ref)`는 플레이어가 다음에 열 만한 게임을 미리 알려 줍니다.

## 요구 사항

공유와 소셜 호출에는 SDK를 쓰는 [패키지](https://www.playdrop.ai/ko/create/learn/packaging)가 필요합니다. 친구 기능에는 로그인한 플레이어가 필요합니다. 호스트가 띄우는 창은 게임을 일시 정지하므로 [일시 정지와 재개](https://www.playdrop.ai/ko/create/learn/lifecycle)를 처리하세요.

## 관련 가이드

- [온라인 파티와 음성 채팅](https://www.playdrop.ai/ko/create/learn/online-party): 친구들이 온라인에서 함께 플레이하게 하세요. 파티 인원수를 선언하고, PlayDrop 파티 창을 열고, sdk.multiplayer.join으로 예약된 방에 참가하고, 방 음성 채팅을 제어하세요.
- [공개 범위와 노출](https://www.playdrop.ai/ko/create/learn/distribution): PlayDrop 게임을 열 수 있는 대상을 고르고, 계정 기본값과 버전 게시가 어떻게 작동하는지, 부스트, 플레이 교환, 인스턴트, 검색이 새 플레이어를 어떻게 데려오는지 알아보세요.
- [순위표](https://www.playdrop.ai/ko/create/learn/leaderboards): catalogue.json에 순위표를 선언하고, sdk.leaderboards로 점수를 제출하고, 상위 순위와 플레이어 주변 순위를 보여 주세요. 점수 유형, 제한, 업데이트 규칙도 담았습니다.