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

استدعِ sdk.host.share() من نقرة أو ضغطة. تشارك الصفحة العامة للعبة مع نص اختياري أو صورة أو فيديو قصير، وبيانات إطلاق اختيارية.

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:

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.

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) إلى اللعبة التي قد يفتحها اللاعب بعد ذلك.

تحتاج استدعاءات المشاركة والميزات الاجتماعية إلى حزمة تستخدم SDK. وتحتاج ميزات الأصدقاء إلى لاعب مسجّل الدخول. وتوقف النوافذ التي يملكها المضيف اللعبة مؤقتًا؛ فعالج الإيقاف المؤقت والاستئناف.