Udostępnianie, znajomi i zaproszenia w grach PlayDrop

Wywołaj sdk.host.share() po dotknięciu lub kliknięciu. Udostępnia publiczną stronę gry z opcjonalnym tekstem, obrazem lub krótkim filmem oraz opcjonalnymi danymi startowymi.

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: obiekt Blob w formacie GIF, JPEG, PNG lub WebP o rozmiarze do 8 MiB. Hosty, które nie mogą dołączać obrazów, udostępniają sam link.
• video: obiekt Blob MP4 trwający najwyżej 15 sekund i mający najwyżej 20 000 000 bajtów, zamiast obrazu. Najlepiej sprawdza się H.264/AAC w 1080p w proporcjach 16:9, 9:16 lub 1:1. Hosty bez obsługi wideo odrzucają wywołanie z host_share_video_unsupported, zamiast udostępnić sam link.
• Przygotuj Blob przed dotknięciem; generowanie go po dotknięciu może sprawić, że przeglądarka cofnie pozwolenie na udostępnienie.
• Nie możesz udostępnić własnego adresu URL ani innych plików. Link zawsze prowadzi do strony gry.

Błędy obrazu to invalid_host_share_image, host_share_image_type i host_share_image_too_large.

payload ma do 256 znaków base64url. Gracz, który otworzy udostępniony link, uruchamia grę z sdk.host.launchPayload ustawionym na tę wartość albo na null. Traktuj je jak niezaufane dane wejściowe: zweryfikuj je i sprawdź na serwerze, czy gracz może dołączyć do wskazanego w nich pokoju. Nigdy nie umieszczaj w nich danych uwierzytelniających.

sdk.social.selectFriends({ max }) otwiera okno wyboru znajomych PlayDrop (od 1 do 10, domyślnie 1) i zwraca tylko znajomych wybranych przez gracza albo [], jeśli anuluje. Potem wyślij kartę, która pojawi się na czacie PlayDrop:

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 ma wartość invite, request, gift, challenge lub turn.
• title ma do 80 znaków, a subtitle do 160.
• expiresInSeconds wynosi od 60 sekund do 30 dni (domyślnie).
• clientMessageId sprawia, że ponowienie jest bezpieczne: ponowne użycie zwraca pierwotną wiadomość.
• Możesz pisać do znajomych wybranych przez gracza, znajomych grających w tę grę i graczy, z którymi już wymienia wiadomości w grze. Do nieznajomych poznanych w dobieraniu graczy nie można pisać.

Odczytuj przychodzące karty przez getMessages({ limit }), od najstarszej, a potem oznaczaj każdą obsłużoną przez consumeMessage(message.id). Nadawcą jest 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);
}

Kontynuuj z cursor: page.nextCursor, dopóki nie będzie miał wartości null.

sdk.social.listGameFriends() zwraca znajomych z niedawną sesją w tej grze: to dobra lista do przycisków „zagraj z”. Nie ujawnia pełnej listy znajomych ani ich obecności. openProfile(userId) otwiera profil gracza, a openChat({ recipientUserId, draftMessage }) otwiera czat z edytowalnym szkicem, który gracz wysyła sam.

Nowy gracz, który przyszedł od znajomego, może mieć ustawione sdk.host.launchFriend. Zaproponuj wspólną grę i potwierdź ją przez selectFriends({ max: 1 }); nigdy niczego nie uruchamiaj automatycznie.

W naturalnej przerwie, na przykład po zakończeniu gry, sdk.host.showGames({ games: ["@creator/name"] }) pokazuje karty PlayDrop od jednej do trzech innych gier publicznych i wstrzymuje twoją. Zwraca played (PlayDrop przełącza wtedy grę) lub dismissed. sdk.host.preloadGame(ref) podpowiada, którą grę gracz może otworzyć jako następną.

Udostępnianie i wywołania społecznościowe wymagają pakietu korzystającego z SDK. Funkcje znajomych wymagają zalogowanego gracza. Okna należące do hosta wstrzymują grę; obsłuż pauzę i wznowienie.