Condivisione, amici e inviti nei giochi PlayDrop

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.

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.

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.

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:

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.

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.

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.

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.

La condivisione e le chiamate social richiedono un pacchetto 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.