# Condivisione, amici e inviti nei giochi PlayDrop

Condividi un gioco con immagine o clip, leggi i dati di avvio, scegli amici, invia carte di invito e sfida nella Chat di PlayDrop e consiglia altri giochi.

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

PlayDrop gestisce la finestra di condivisione, la lista degli amici e la chat; il tuo gioco le apre al momento giusto. I giocatori portano i loro amici, e gli amici arrivano nel tuo gioco.

## Condividi il gioco

Chiama `sdk.host.share()` da un tocco o un clic. Condivide la pagina pubblica del gioco con testo facoltativo, un’immagine o un breve video, e dati di avvio facoltativi.

```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`: un Blob GIF, JPEG, PNG o WebP fino a 8 MiB. Gli host che non possono allegare immagini condividono solo il link.
- `video`: un Blob MP4 di al massimo 15 secondi e 20.000.000 byte, al posto di un’immagine. H.264/AAC a 1080p in 16:9, 9:16 o 1:1 dà i risultati migliori. Gli host senza supporto video rifiutano con `host_share_video_unsupported` invece di condividere un semplice link.
- Prepara il Blob prima del tocco; generarlo dopo il tocco può far perdere al browser il permesso di condividere.
- Non puoi condividere un URL personalizzato o altri file. Il link è sempre la pagina del gioco.

Gli errori sulle immagini sono `invalid_host_share_image`, `host_share_image_type` e `host_share_image_too_large`.

## Leggi i dati di avvio

`payload` contiene fino a 256 caratteri base64url. Un giocatore che apre il link condiviso avvia il gioco con `sdk.host.launchPayload` impostato su quel valore, oppure `null`. Trattalo come un input non affidabile: convalidalo e verifica sul tuo server che il giocatore possa entrare nella stanza che indica. Non metterci mai credenziali.

## Scegli gli amici e invia carte di gioco

`sdk.social.selectFriends({ max })` apre il selettore di amici di PlayDrop (da 1 a 10, predefinito 1) e restituisce solo gli amici scelti dal giocatore, oppure `[]` se annulla. Poi invia una carta che compare nella Chat di 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` vale `invite`, `request`, `gift`, `challenge` o `turn`.
- `title` ha fino a 80 caratteri e `subtitle` fino a 160.
- `expiresInSeconds` va da 60 secondi a 30 giorni (il valore predefinito).
- `clientMessageId` rende sicuro un nuovo tentativo: riutilizzarlo restituisce il messaggio originale.
- Puoi inviare messaggi agli amici scelti dal giocatore, agli amici che giocano a questo gioco e ai giocatori con cui scambia già messaggi di gioco. Non puoi scrivere agli sconosciuti incontrati nel matchmaking.

Leggi le carte in arrivo con `getMessages({ limit })`, dalla più vecchia, poi segna ciascuna come gestita con `consumeMessage(message.id)`. Il mittente è `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);
}
```

Continua con `cursor: page.nextCursor` finché non è `null`.

## Amici che giocano a questo gioco

`sdk.social.listGameFriends()` restituisce gli amici con una sessione recente in questo gioco: un buon elenco per i pulsanti «gioca con». Non espone la lista completa degli amici né la loro presenza online. `openProfile(userId)` apre il profilo di un giocatore e `openChat({ recipientUserId, draftMessage })` apre la Chat con una bozza modificabile che il giocatore invia di persona.

Un nuovo giocatore arrivato tramite un amico può avere `sdk.host.launchFriend` impostato. Proponi di giocare con quell’amico e conferma con `selectFriends({ max: 1 })`; non avviare mai nulla in automatico.

## Consiglia altri giochi

In una pausa naturale, come il game over, `sdk.host.showGames({ games: ["@creator/name"] })` mostra le carte di PlayDrop di uno, due o tre altri giochi pubblici e mette in pausa il tuo. Si risolve con `played` (PlayDrop passa allora all’altro gioco) oppure `dismissed`. `sdk.host.preloadGame(ref)` indica il gioco che il giocatore potrebbe aprire dopo.

## Requisiti

La condivisione e le chiamate social richiedono un [pacchetto](https://www.playdrop.ai/it/create/learn/packaging) che usa l’SDK. Le funzioni per gli amici richiedono un giocatore che ha effettuato l’accesso. Le finestre gestite dall’host mettono in pausa il gioco; gestisci [pausa e ripresa](https://www.playdrop.ai/it/create/learn/lifecycle).

## Guide correlate

- [Gruppi online e voce](https://www.playdrop.ai/it/create/learn/online-party): Fai giocare gli amici insieme online: dimensioni dei gruppi, finestra del gruppo di PlayDrop, stanze riservate con sdk.multiplayer.join e voce della stanza.
- [Visibilità e pubblico](https://www.playdrop.ai/it/create/learn/distribution): Scegli chi può aprire un gioco, capisci l’impostazione predefinita e le versioni, e scopri come Boost, Scambio di partite, Instant e ricerca portano giocatori.
- [Classifiche](https://www.playdrop.ai/it/create/learn/leaderboards): Dichiara le classifiche in catalogue.json, invia punteggi con sdk.leaderboards e mostra i primi posti e i vicini del giocatore. Tipi, limiti e aggiornamenti.