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을 준비하세요. 탭한 뒤에 만들면 브라우저의 공유 권한을 잃을 수 있습니다.
• 사용자 지정 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에 표시되는 카드를 보내세요.

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

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

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

공유와 소셜 호출에는 SDK를 쓰는 패키지가 필요합니다. 친구 기능에는 로그인한 플레이어가 필요합니다. 호스트가 띄우는 창은 게임을 일시 정지하므로 일시 정지와 재개를 처리하세요.