# المشاركة والأصدقاء والدعوات في ألعاب PlayDrop

شارك لعبة مع صورة أو مقطع، واقرأ بيانات الإطلاق، واختر الأصدقاء، وأرسل بطاقات الدعوة والتحدي في دردشة PlayDrop، واقترح ألعابًا أخرى.

Source: https://www.playdrop.ai/ar/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`: كائن Blob بصيغة GIF أو JPEG أو PNG أو WebP حتى 8 MiB. والبيئات المضيفة التي لا تستطيع إرفاق الصور تشارك الرابط وحده.
- `video`: كائن Blob بصيغة MP4 لا تتجاوز مدته 15 ثانية وحجمه 20,000,000 بايت، بدل الصورة. ويعمل H.264/AAC بدقة 1080p بنسبة 16:9 أو 9:16 أو 1:1 على أفضل وجه. والبيئات المضيفة التي لا تدعم الفيديو ترفض الطلب بالخطأ `host_share_video_unsupported` بدل مشاركة رابط عادي.
- جهّز كائن Blob قبل النقرة؛ فإنشاؤه بعد النقرة قد يُفقدك إذن المتصفح بالمشاركة.
- لا يمكنك مشاركة رابط مخصص أو ملفات أخرى. الرابط هو دائمًا صفحة اللعبة.

أخطاء الصور هي `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:

```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);
}
```

تابع باستخدام `cursor: page.nextCursor` حتى تصبح قيمته `null`.

## الأصدقاء الذين يلعبون هذه اللعبة

تعيد `sdk.social.listGameFriends()` الأصدقاء الذين لديهم جلسة حديثة في هذه اللعبة: قائمة جيدة لأزرار «العب مع». ولا تكشف قائمة الأصدقاء الكاملة ولا حالة الاتصال. تفتح `openProfile(userId)` الملف الشخصي للاعب، وتفتح `openChat({ recipientUserId, draftMessage })` الدردشة مع مسودة قابلة للتعديل يرسلها اللاعب بنفسه.

قد تكون `sdk.host.launchFriend` مضبوطة للاعب جديد وصل عن طريق صديق. اعرض عليه اللعب مع ذلك الصديق وأكّد ذلك باستخدام `selectFriends({ max: 1 })`؛ ولا تبدأ أي شيء تلقائيًا أبدًا.

## اقترح ألعابًا أخرى

عند استراحة طبيعية، مثل نهاية اللعبة، تعرض `sdk.host.showGames({ games: ["@creator/name"] })` بطاقات PlayDrop لعدد من لعبة إلى ثلاث ألعاب عامة أخرى وتوقف لعبتك مؤقتًا. وتكتمل بالقيمة `played` (ثم ينتقل PlayDrop إلى اللعبة الأخرى) أو `dismissed`. وتلمّح `sdk.host.preloadGame(ref)` إلى اللعبة التي قد يفتحها اللاعب بعد ذلك.

## المتطلبات

تحتاج استدعاءات المشاركة والميزات الاجتماعية إلى [حزمة](https://www.playdrop.ai/ar/create/learn/packaging) تستخدم SDK. وتحتاج ميزات الأصدقاء إلى لاعب مسجّل الدخول. وتوقف النوافذ التي يملكها المضيف اللعبة مؤقتًا؛ فعالج [الإيقاف المؤقت والاستئناف](https://www.playdrop.ai/ar/create/learn/lifecycle).

## أدلة ذات صلة

- [المجموعات والصوت عبر الإنترنت](https://www.playdrop.ai/ar/create/learn/online-party): دع الأصدقاء يلعبون معًا عبر الإنترنت: صرّح بأحجام المجموعات، وافتح نافذة المجموعة، وانضم إلى الغرف المحجوزة عبر sdk.multiplayer.join، وتحكم بصوت الغرفة.
- [الظهور والانتشار](https://www.playdrop.ai/ar/create/learn/distribution): اختر من يمكنه فتح لعبة على PlayDrop، وكيف يعمل الإعداد الافتراضي للحساب ونشر الإصدارات، وكيف يجلب التعزيز وتبادل اللعب وInstant والبحث لاعبين جددًا.
- [لوحات المتصدرين](https://www.playdrop.ai/ar/create/learn/leaderboards): صرّح بلوحات المتصدرين في catalogue.json، وأرسل النقاط عبر sdk.leaderboards، واعرض المراتب الأولى وجيران اللاعب. أنواع النقاط والحدود وقواعد التحديث.