Compartir, amigos e invitaciones en juegos de PlayDrop

Llama a sdk.host.share() a partir de un toque o un clic. Comparte la página pública del juego con un texto, una imagen o un vídeo corto opcionales, y unos datos de lanzamiento opcionales.

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 de hasta 8 MiB. Los hosts que no pueden adjuntar imágenes comparten solo el enlace.
• video: un Blob MP4 de 15 segundos y 20.000.000 bytes como máximo, en lugar de una imagen. Funciona mejor en H.264/AAC a 1080p en 16:9, 9:16 o 1:1. Los hosts que no admiten vídeo rechazan la acción con host_share_video_unsupported en lugar de compartir solo el enlace.
• Prepara el Blob antes del toque; si lo generas después, el navegador puede retirar el permiso para compartir.
• No puedes compartir una URL personalizada ni otros archivos. El enlace es siempre la página del juego.

Los errores de imagen son invalid_host_share_image, host_share_image_type y host_share_image_too_large.

payload admite hasta 256 caracteres base64url. Un jugador que abre el enlace compartido inicia el juego con sdk.host.launchPayload establecido en ese valor, o en null. Trátalo como una entrada no fiable: valídalo y comprueba en tu servidor que el jugador puede entrar en la sala que indique. Nunca incluyas credenciales en él.

sdk.social.selectFriends({ max }) abre el selector de amigos de PlayDrop (de 1 a 10, 1 por defecto) y devuelve solo los amigos que eligió el jugador, o [] si cancela. Después, envía una tarjeta que aparece en 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 es invite, request, gift, challenge o turn.
• title admite hasta 80 caracteres y subtitle, hasta 160.
• expiresInSeconds va de 60 segundos a 30 días (el valor por defecto).
• clientMessageId hace que reintentar sea seguro: si lo reutilizas, se devuelve el mensaje original.
• Puedes enviar mensajes a los amigos que eligió el jugador, a los amigos que juegan a este juego y a los jugadores con los que ya intercambia mensajes de juego. No se pueden enviar mensajes a desconocidos encontrados en el emparejamiento.

Lee las tarjetas recibidas con getMessages({ limit }), de la más antigua a la más reciente, y marca cada una como gestionada con consumeMessage(message.id). El remitente es 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);
}

Continúa con cursor: page.nextCursor hasta que sea null.

sdk.social.listGameFriends() devuelve los amigos con una sesión reciente en este juego: una buena lista para botones de «jugar con». No expone la lista completa de amigos ni su presencia. openProfile(userId) abre el perfil de un jugador y openChat({ recipientUserId, draftMessage }) abre el Chat con un borrador editable que el jugador envía por sí mismo.

Un jugador nuevo que llegó a través de un amigo puede tener sdk.host.launchFriend establecido. Ofrécele jugar con ese amigo y confírmalo con selectFriends({ max: 1 }); nunca inicies nada automáticamente.

En una pausa natural, como el final de la partida, sdk.host.showGames({ games: ["@creator/name"] }) muestra tarjetas de PlayDrop de uno a tres juegos públicos más y pausa el tuyo. Se resuelve con played (y PlayDrop cambia de juego) o con dismissed. sdk.host.preloadGame(ref) anticipa el juego que el jugador podría abrir a continuación.

Las llamadas para compartir y las sociales necesitan un paquete que use el SDK. Las funciones de amigos necesitan un jugador con la sesión iniciada. Las ventanas del host pausan el juego; gestiona la pausa y la reanudación.