# PlayDrop ゲームの共有、フレンド、招待

画像やクリップを添えてゲームを共有し、起動ペイロードを読み取り、フレンドを選んで PlayDrop Chat で招待カードや挑戦カードを送り、ほかのゲームをおすすめします。

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

共有シート、フレンドリスト、チャットは PlayDrop が担当し、ゲームはちょうどいいタイミングでそれらを呼び出します。プレイヤーが友達を連れてきて、その友達があなたのゲームにやって来ます。

## ゲームを共有する

タップやクリックから `sdk.host.share()` を呼び出します。ゲームの公開ページを、任意のテキスト、画像または短い動画、任意の起動ペイロードを添えて共有します。

```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`：最大 8 MiB の GIF、JPEG、PNG、WebP の Blob。画像を添付できないホストでは、リンクだけが共有されます。
- `video`：画像の代わりに使う、最大15秒、20,000,000 バイトの MP4 の Blob。16:9、9:16、1:1 の 1080p、H.264/AAC がいちばん適しています。動画に対応していないホストは、普通のリンクを共有するのではなく、`host_share_video_unsupported` で拒否します。
- Blob はタップの前に用意しておいてください。タップのあとで生成すると、ブラウザの共有の許可が失われることがあります。
- 独自の URL やほかのファイルは共有できません。リンクは常にゲームのページです。

画像のエラーは `invalid_host_share_image`、`host_share_image_type`、`host_share_image_too_large` です。

## 起動ペイロードを読み取る

`payload` は最大256文字の base64url です。共有リンクを開いたプレイヤーがゲームを始めると、`sdk.host.launchPayload` にその値が入ります。ない場合は `null` です。信頼できない入力として扱ってください。内容を検証し、ペイロードが指すルームにそのプレイヤーが参加してよいかをサーバーで確認します。認証情報は絶対に入れないでください。

## フレンドを選んでゲームカードを送る

`sdk.social.selectFriends({ max })` は PlayDrop のフレンド選択画面（1〜10人、既定は1人）を開き、プレイヤーが選んだフレンドだけを返します。キャンセルした場合は `[]` を返します。そのあと、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`、`turn` のいずれかです。
- `title` は最大80文字、`subtitle` は最大160文字です。
- `expiresInSeconds` は60秒から30日（既定値）までです。
- `clientMessageId` があると安全に再試行できます。同じ値を再利用すると、元のメッセージが返されます。
- メッセージを送れる相手は、プレイヤーが選んだフレンド、このゲームを遊んでいるフレンド、すでにゲームのメッセージをやり取りしているプレイヤーです。マッチメイキングで出会った知らない人にはメッセージを送れません。

届いたカードは `getMessages({ limit })` で古い順に読み取り、それぞれ `consumeMessage(message.id)` で処理済みにします。送信者は `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);
}
```

`null` になるまで、`cursor: page.nextCursor` で続きを読み取ります。

## このゲームを遊んでいるフレンド

`sdk.social.listGameFriends()` は、このゲームで最近セッションがあったフレンドを返します。「一緒に遊ぶ」ボタンにちょうどいいリストです。フレンドリスト全体やオンライン状態は公開されません。`openProfile(userId)` はプレイヤーのプロフィールを開き、`openChat({ recipientUserId, draftMessage })` は、編集できる下書き付きでチャットを開きます。送信するのはプレイヤー自身です。

友達経由でやって来た新しいプレイヤーには、`sdk.host.launchFriend` が設定されていることがあります。その友達と一緒に遊ぶことを提案し、`selectFriends({ max: 1 })` で確認してください。何かを自動で始めるのは絶対にやめてください。

## ほかのゲームをおすすめする

ゲームオーバーなどの自然な区切りで `sdk.host.showGames({ games: ["@creator/name"] })` を呼び出すと、ほかの公開ゲーム1〜3本の PlayDrop カードを表示し、あなたのゲームを一時停止します。結果は `played`（PlayDrop がそのゲームに切り替えます）か `dismissed` です。`sdk.host.preloadGame(ref)` は、プレイヤーが次に開きそうなゲームを PlayDrop に伝えます。

## 必要なもの

共有とソーシャルの呼び出しには、SDK を使う[パッケージ](https://www.playdrop.ai/ja/create/learn/packaging)が必要です。フレンドの機能には、サインイン中のプレイヤーが必要です。ホストのウィンドウはゲームを一時停止するので、[一時停止と再開](https://www.playdrop.ai/ja/create/learn/lifecycle)に対応してください。

## 関連ガイド

- [オンラインパーティーと音声](https://www.playdrop.ai/ja/create/learn/online-party): 友達どうしでオンラインで一緒に遊べるようにします。パーティーの人数を宣言し、PlayDrop のパーティー画面を開き、sdk.multiplayer.join で予約済みのルームに参加し、ルーム音声を制御します。
- [公開範囲と集客](https://www.playdrop.ai/ja/create/learn/distribution): PlayDrop のゲームを誰が開けるかの選び方、アカウントの既定設定とバージョン公開のしくみ、ブースト、プレイ交換、インスタント、検索で新しいプレイヤーを集める方法を説明します。
- [ランキング](https://www.playdrop.ai/ja/create/learn/leaderboards): catalogue.json でランキングを宣言し、sdk.leaderboards でスコアを送信して、上位とプレイヤー周辺の順位を表示します。スコアの種類、制限、更新のルールも説明します。