# Udostępnianie, znajomi i zaproszenia w grach PlayDrop

Udostępniaj grę z obrazem lub klipem, odczytuj dane startowe, wybieraj znajomych, wysyłaj karty zaproszeń i wyzwań na czacie PlayDrop oraz polecaj inne gry.

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

PlayDrop obsługuje arkusz udostępniania, listę znajomych i czat; twoja gra prosi o nie we właściwym momencie. Gracze przyprowadzają znajomych, a znajomi trafiają prosto do twojej gry.

## Udostępnij grę

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.

```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`: 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`.

## Odczytaj dane startowe

`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.

## Wybierz znajomych i wyślij karty gier

`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:

```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` 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`.

```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);
}
```

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

## Znajomi grający w tę grę

`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.

## Polecaj inne gry

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ą.

## Wymagania

Udostępnianie i wywołania społecznościowe wymagają [pakietu](https://www.playdrop.ai/pl/create/learn/packaging) korzystającego z SDK. Funkcje znajomych wymagają zalogowanego gracza. Okna należące do hosta wstrzymują grę; obsłuż [pauzę i wznowienie](https://www.playdrop.ai/pl/create/learn/lifecycle).

## Powiązane poradniki

- [Grupy online i głos](https://www.playdrop.ai/pl/create/learn/online-party): Pozwól znajomym grać razem online: zadeklaruj rozmiary grup, otwórz okno grupy, dołączaj do zarezerwowanych pokoi przez sdk.multiplayer.join i steruj głosem.
- [Widoczność i zasięg](https://www.playdrop.ai/pl/create/learn/distribution): Wybierz, kto może otworzyć grę, poznaj ustawienie konta i publikowanie wersji oraz to, jak Boost, Wymiana rozgrywek, Instant i wyszukiwarki przyciągają graczy.
- [Rankingi](https://www.playdrop.ai/pl/create/learn/leaderboards): Zadeklaruj rankingi w catalogue.json, wysyłaj wyniki przez sdk.leaderboards i pokazuj czołówkę oraz sąsiadów gracza. Typy wyników, limity i zasady zmian.