# Sharing, friends and invites in PlayDrop games

Share a game with an image or clip, read launch payloads, pick friends, send invite and challenge cards in PlayDrop Chat, and recommend other games.

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

PlayDrop handles the share sheet, friend list and chat; your game asks for them at the right moment. Players bring their friends, and the friends land in your game.

## Share the game

Call `sdk.host.share()` from a tap or click. It shares the game's public page with optional text, an image or a short video, and an optional launch payload.

```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`: a GIF, JPEG, PNG or WebP Blob up to 8 MiB. Hosts that cannot attach images share the link alone.
- `video`: an MP4 Blob of at most 15 seconds and 20,000,000 bytes, instead of an image. H.264/AAC at 1080p in 16:9, 9:16 or 1:1 works best. Hosts without video support reject with `host_share_video_unsupported` rather than share a plain link.
- Prepare the Blob before the tap; generating it after the tap can lose the browser's permission to share.
- You cannot share a custom URL or other files. The link is always the game's page.

Image errors are `invalid_host_share_image`, `host_share_image_type` and `host_share_image_too_large`.

## Read the launch payload

`payload` is up to 256 base64url characters. A player who opens the shared link starts the game with `sdk.host.launchPayload` set to it, or `null`. Treat it as untrusted input: validate it, and check on your server that the player may join a room it names. Never put credentials in it.

## Pick friends and send game cards

`sdk.social.selectFriends({ max })` opens PlayDrop's friend picker (1 to 10, default 1) and returns only the friends the player chose, or `[]` if they cancel. Then send a card that appears in 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` is `invite`, `request`, `gift`, `challenge` or `turn`.
- `title` is up to 80 characters and `subtitle` up to 160.
- `expiresInSeconds` is 60 seconds to 30 days (the default).
- `clientMessageId` makes a retry safe: reusing it returns the original message.
- You can message friends the player selected, friends who play this game, and players they already exchange game messages with. Strangers met in matchmaking cannot be messaged.

Read incoming cards with `getMessages({ limit })`, oldest first, then mark each handled with `consumeMessage(message.id)`. The sender is `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 with `cursor: page.nextCursor` until it is `null`.

## Friends who play this game

`sdk.social.listGameFriends()` returns friends with a recent session in this game: a good list for "play with" buttons. It does not expose the full friend list or presence. `openProfile(userId)` opens a player's profile and `openChat({ recipientUserId, draftMessage })` opens Chat with an editable draft that the player sends themselves.

A new player who arrived from a friend may have `sdk.host.launchFriend` set. Offer to play with them and confirm with `selectFriends({ max: 1 })`; never start anything automatically.

## Recommend other games

At a natural break, such as game over, `sdk.host.showGames({ games: ["@creator/name"] })` shows PlayDrop cards for one to three other public games and pauses yours. It resolves `played` (PlayDrop then switches games) or `dismissed`. `sdk.host.preloadGame(ref)` hints at the game the player may open next.

## Requirements

Sharing and social calls need a [package](https://www.playdrop.ai/create/learn/packaging) that uses the SDK. Friends features need a signed-in player. Host-owned windows pause the game; handle [pause and resume](https://www.playdrop.ai/create/learn/lifecycle).

## Related guides

- [Online parties and voice](https://www.playdrop.ai/create/learn/online-party): Let friends play together online: declare party sizes, open PlayDrop's party window, join reserved rooms with sdk.multiplayer.join and control room voice.
- [Visibility and reach](https://www.playdrop.ai/create/learn/distribution): Choose who can open a PlayDrop game, how the account default and version publishing work, and how Boost, PlayTrade, Instant and search bring new players.
- [Leaderboards](https://www.playdrop.ai/create/learn/leaderboards): Declare leaderboards in catalogue.json, submit scores with sdk.leaderboards and show top ranks and the player's neighbors. Score types, limits and update rules.