# Compartilhamento, amigos e convites em jogos do PlayDrop

Compartilhe um jogo com imagem ou clipe, leia os dados de abertura, escolha amigos, envie cards de convite e desafio no PlayDrop Chat e recomende outros jogos.

Source: https://www.playdrop.ai/pt-br/create/learn/social

O PlayDrop cuida da janela de compartilhamento, da lista de amigos e do chat; seu jogo pede esses recursos no momento certo. Os jogadores trazem os amigos, e os amigos chegam direto no seu jogo.

## Compartilhe o jogo

Chame `sdk.host.share()` a partir de um toque ou de um clique. A chamada compartilha a página pública do jogo com um texto opcional, uma imagem ou um vídeo curto e dados de abertura opcionais.

```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`: um Blob GIF, JPEG, PNG ou WebP de até 8 MiB. Os hosts que não conseguem anexar imagens compartilham só o link.
- `video`: um Blob MP4 de no máximo 15 segundos e 20.000.000 bytes, no lugar de uma imagem. H.264/AAC em 1080p, em 16:9, 9:16 ou 1:1, funciona melhor. Os hosts sem suporte a vídeo rejeitam a chamada com `host_share_video_unsupported` em vez de compartilhar só o link.
- Prepare o Blob antes do toque; gerá-lo depois do toque pode fazer o navegador perder a permissão para compartilhar.
- Não é possível compartilhar uma URL personalizada nem outros arquivos. O link é sempre a página do jogo.

Os erros de imagem são `invalid_host_share_image`, `host_share_image_type` e `host_share_image_too_large`.

## Leia os dados de abertura

`payload` tem até 256 caracteres base64url. Um jogador que abre o link compartilhado inicia o jogo com `sdk.host.launchPayload` definido com esse valor, ou com `null`. Trate esse valor como uma entrada não confiável: valide-o e verifique no seu servidor se o jogador pode entrar em uma sala indicada nele. Nunca coloque credenciais nele.

## Escolha amigos e envie cards de jogo

`sdk.social.selectFriends({ max })` abre o seletor de amigos do PlayDrop (de 1 a 10; o padrão é 1) e retorna só os amigos que o jogador escolheu, ou `[]` se ele cancelar. Depois, envie um card que aparece no PlayDrop Chat:

```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` é `invite`, `request`, `gift`, `challenge` ou `turn`.
- `title` tem até 80 caracteres e `subtitle`, até 160.
- `expiresInSeconds` vai de 60 segundos a 30 dias (o padrão).
- `clientMessageId` torna uma nova tentativa segura: reutilizá-lo retorna a mensagem original.
- Você pode enviar mensagens aos amigos que o jogador selecionou, aos amigos que jogam este jogo e aos jogadores com quem ele já troca mensagens de jogo. Desconhecidos encontrados na formação de partidas não podem receber mensagens.

Leia os cards recebidos com `getMessages({ limit })`, dos mais antigos para os mais recentes, e depois marque cada um como tratado com `consumeMessage(message.id)`. O remetente é `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);
}
```

Continue com `cursor: page.nextCursor` até que ele seja `null`.

## Amigos que jogam este jogo

`sdk.social.listGameFriends()` retorna os amigos com uma sessão recente neste jogo: uma boa lista para botões de "jogar com". Ela não expõe a lista completa de amigos nem quem está online. `openProfile(userId)` abre o perfil de um jogador e `openChat({ recipientUserId, draftMessage })` abre o Chat com um rascunho editável que o próprio jogador envia.

Um jogador novo que chegou por meio de um amigo pode ter `sdk.host.launchFriend` definido. Ofereça jogar com esse amigo e confirme com `selectFriends({ max: 1 })`; nunca inicie nada automaticamente.

## Recomende outros jogos

Em uma pausa natural, como o fim de jogo, `sdk.host.showGames({ games: ["@creator/name"] })` mostra cards do PlayDrop de um a três outros jogos públicos e pausa o seu. A chamada é resolvida com `played` (o PlayDrop então troca de jogo) ou `dismissed`. `sdk.host.preloadGame(ref)` indica o jogo que o jogador pode abrir em seguida.

## Requisitos

O compartilhamento e as chamadas sociais precisam de um [pacote](https://www.playdrop.ai/pt-br/create/learn/packaging) que use o SDK. Os recursos de amigos exigem um jogador logado. As janelas do host pausam o jogo; trate a [pausa e a retomada](https://www.playdrop.ai/pt-br/create/learn/lifecycle).

## Guias relacionados

- [Grupos online e voz](https://www.playdrop.ai/pt-br/create/learn/online-party): Amigos jogam juntos online: declare tamanhos de grupo, abra a janela de grupo do PlayDrop, entre em salas reservadas com sdk.multiplayer.join e controle a voz.
- [Visibilidade e alcance](https://www.playdrop.ai/pt-br/create/learn/distribution): Escolha quem pode abrir seu jogo, entenda o padrão da conta e a publicação de versões e como Boost, troca de partidas, Instantâneo e busca trazem jogadores.
- [Placares](https://www.playdrop.ai/pt-br/create/learn/leaderboards): Declare placares no catalogue.json, envie pontuações com sdk.leaderboards e mostre o topo e os vizinhos do jogador. Tipos de pontuação, limites e atualizações.