طلبات الألعاب

توفر طلبات الألعاب للاعبين آلية تتيح لهم دعوة أصدقائهم لتشغيل إحدى الألعاب. يرسل أحد اللاعبين الطلبات إلى صديق واحد أو أكثر، وتنطوي الطلبات دومًا على دعوة لاتخاذ إجراء للعبة. قد يكون المستلمون لاعبين موجودين أو لاعبين جدد.

يمكن استخدام طلبات الألعاب لجذب لاعبين جدد أو لإعادة جذب اللاعبين الموجودين من جديد. يمكن إرسال الطلبات في سيناريوهين:

1. أن يكون المستلم صديقًا للمرسل، ولم يقم بمصادقة اللعبة. وهذا السيناريو مفيد للدعوات.
2. أن يكون المستلم صديقًا للمرسل، وقام بمصادقة اللعبة من قبل. يُهد هذا السيناريو مفيدًا للإشعارات المستندة إلى دور وطلب المساعدة.

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

مثال على طلب لعبة يظهر على فيسبوك للكمبيوتر.

تتوفر طلبات الألعاب لكل من الألعاب على فيسبوك وألعاب الهواتف المحمولة على iOS وAndroid. على موقع الكمبيوتر لفيسبوك، تظهر الطلبات كرسالة تنبيه منبثقة في الركن السفلي الأيمن من الشاشة وكذلك في جوهرة الإشعارات، في حالة عدم فلترتها. أما على منصات الهواتف المحمولة، فستظهر الطلبات في قائمة الإشعارات في تطبيق فيسبوك، في حالة عدم فلترتها. تتوفر بيانات الطلب من خلال API طلب اللعبة، ويمكن إنشاء واجهات مستخدم مخصصة للاستمتاع بتجربة أكثر دمجًا في ألعاب الهواتف المحمولة. لذلك، ينبغي أن يتم تنفيذ الطلبات بشكل غير محدد للمنصة، كما ينبغي أن يوفر تجربة متسقة للمستخدم، بغض النظر عن المنصة المستخدمة. على الرغم من ذلك، ستظهر الدعوات التي يرسلها اللاعب على أية مجموعة من المنصات تدعمها اللعبة.

تشغيل مربع حوار الطلب

يتم إنشاء مربع حوار طلب اللعبة عبر مجموعة SDK لمنصة Unity وJavaScript وiOS وAndroid. تفترض هذه الأمثلة أن المرسل قام بمصادقة التطبيق بالفعل. إذا لم يتم تحديد أي مستلمين، فيمكنك فلترة قائمة الأصدقاء حتى 50 صديقًا أو أقل، كما يمكنك تقسيمهم إلى شرائح حسب اللاعبين المسجلين أو الأصدقاء غير المسجلين. يفيد ذلك في توفير دفق منفصل لإعادة جذب اللاعبين الموجودين أو لدعوة آخرين جدد.

JavaScript

إرسال الطلبات باستخدام أداة تحديد الأصدقاء المتعددين المتوفرة عن طريق مربع حوار طلب اللعبة:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE'
}, function(response){
  console.log(response);
});

عند إغلاق مربع الحوار، سيحتوي الكائن response على نتائج عملية الإرسال، بما في ذلك معرف request ومصفوفة من مستلمي to. على سبيل المثال:

{
  "request":"1428237347457728",
  "to":["10150002163885335"]
}

يتم عرضه بشكل افتراضي على المرسل أداة تحديد أصدقاء متعددين تتيح له تحديد 50 مستلمًا بحد أقصى.

إرسال الطلبات إلى مستلم محدد:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID'
}, function(response){
  console.log(response);
});

إذا تم تحديد الحقل to، فلن يتمكن المرسل من تحديد مستلمين إضافيين.

إرسال الطلبات إلى مستلمين محددين متعددين:

FB.ui({method: 'apprequests',
  message: 'YOUR_MESSAGE_HERE',
  to: 'USER_ID, USER_ID, USER_ID'
}, function(response){
  console.log(response);
});

يمكن تحديد مستلمين متعددين من خلال قائمة مفصولة بفاصلة تحتوي على مزيج من معرفات المستخدمين.

إرسال الطلبات إلى قائمة محددة من الأصدقاء:

FB.ui({method: 'apprequests',
  message: 'Friend Smash Request!',
  filters: [{name:'GROUP_1_NAME', user_ids:['USER_ID','USER_ID','USER_ID']},{name:'GROUP_2_NAME', user_ids: ['USER_ID','USER_ID','USER_ID']}]
}, function(response){
  console.log(response);
}});

إرسال الكائنات عبر الطلبات، عن طريق تحديد action_type وobject_id بوضوح:

FB.ui({method: 'apprequests',
  message: 'Take this bomb to blast your way to victory!',
  to: {user-ids},
  action_type:'send',
  object_id: 'YOUR_OBJECT_ID'  // e.g. '191181717736427'
}, function(response){
  console.log(response);
});

بالنسبة إلى الطلبات التي تستند إلى الدور، لا تحدد object_id.

FB.ui({method: 'apprequests',
  message: 'Just smashed you 78 times! It\'s your turn.',
  to: {user-ids},
  action_type:'turn'
}, function(response){
  console.log(response);
});

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

لمزيد من المعلومات، يُرجى الرجوع إلى وثائق FB.ui المرجعية لمجموعة Facebook SDK للغة JavaScript.

مجموعة SDK لنظام iOS

تشغيل مربع حوار الطلب باستخدام أداة تحديد الأصدقاء المتوفرة عن طريق مجموعة iOS SDK:

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
// Look at FBSDKGameRequestContent for futher optional properties
gameRequestContent.message = @"YOUR_MESSAGE_HERE";
gameRequestContent.title = @"OPTIONAL TITLE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

إرسال الطلبات التي تحدد بوضوح action_type وobject_id إلى مستلم محدد باستخدام مجموعة iOS SDK:

FBSDKGameRequestContent *gameRequestContent = [[FBSDKGameRequestContent alloc] init];
gameRequestContent.message = @"Take this bomb to blast your way to victory!";
gameRequestContent.to = @[@"RECIPIENT_USER_ID"];
gameRequestContent.objectID = @"YOUR_OBJECT_ID";
gameRequestContent.actionType = @"ACTION_TYPE";

// Assuming self implements <FBSDKGameRequestDialogDelegate>
[FBSDKGameRequestDialog showWithContent:gameRequestContent delegate:self];

مجموعة Android SDK

إرسال طلب باستخدام أداة تحديد الأصدقاء الخاصة بمربع حوار الطلب عبر مجموعة Android SDK:

GameRequestDialog requestDialog;
CallbackManager callbackManager;

public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  FacebookSdk.sdkInitialize(this.getApplicationContext());
  callbackManager = CallbackManager.Factory.create();
  requestDialog = new GameRequestDialog(this);
  requestDialog.registerCallback(callbackManager,
    new FacebookCallback<GameRequestDialog.Result>() {
    public void onSuccess(GameRequestDialog.Result result) {
      String id = result.getId();
    }
    public void onCancel() {}
      public void onError(FacebookException error) {}
    }
  );
}

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .build();
  requestDialog.show(content);
}

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  callbackManager.onActivityResult(requestCode, resultCode, data);
}

إرسال طلب يحدد بوضوح إجراءً وكائنًا باستخدام مجموعة Android SDK:

private void onClickRequestButton() {
  GameRequestContent content = new GameRequestContent.Builder()
    .setMessage("Come play this level with me")
    .setTo("USER_ID")
    .setActionType(ActionType.SEND)
    .setObjectId("YOUR_OBJECT_ID")
    .build();
  requestDialog.show(content);
}

مجموعة SDK لمنصة Unity

يتم فيما يلي توضيح كيفية إجراء الطلبات في مجموعة SDK لمنصة Unity. يُرجى مراجعة وثائق FB.AppRequest للتعرف على مزيد من التفاصيل.

FB.AppRequest(
  message: "I Just got " + GameStateManager.Score.ToString() + " points! Can you beat it?",
  to: recipients,
  data: "{\"challenge_score\":" + GameStateManager.Score.ToString() + "}"
  title: "Friend Smash Challenge!",
  callback:appRequestCallback
);

معلمات مربع الحوار

يمكن إنشاء مربع حوار طلب اللعبة باستخدام عدد من المعلمات الإضافية التي تحدد سلوكه. يتم توضيح هذه المعلمات أدناه.

بيانات الاستجابة

عندما يتم إرسال طلب عبر مربع حوار طلب اللعبة، يتم تمرير استجابة إلى الاستدعاء بحيث تحتوي على المعلومات التالية:

معالجة الطلبات في اللعبة

قبول الطلبات

عندما يقبل أحد المستلمين طلبًا على موقع الكمبيوتر لفيسبوك، فسيتم إرسال له عنوان URL للعبة التي أرسلت الطلب. سيحتوي عنوان URL هذا على معلمة GET إضافية هي request_ids، وهي عبارة عن قائمة مفصولة بفاصلات لمعرفات الطلبات التي يقبلها المستخدم:

http://apps.facebook.com/[app_name]/?request_ids=[REQUEST_IDs]

لا يتم حذف الطلبات تلقائيًا عندما يقبلها المستلم. حيث تقع مسؤولية حذفها على لعبتك. من النهج الشائعة عند تشغيل لعبتك، قراءة قائمة الطلبات المعلقة لذلك المستخدم من Graph API ثم حذف كل طلب بعد معالجته.

عندما يقبل المستلم طلبًا على منصة الهواتف المحمولة، فسيتم وضع رابط لموضع معين للتطبيق. ستوجد معلمة إضافية في تحميل التطبيق، هي معرف الطلب. تنطبق مسؤولية قبول الطلبات ومسحها ذاتها على الهواتف المحمولة أيضًا. يُعد تحديد الطلبات المعلقة ومسحها عند تشغيل اللعبة من الممارسات الجيدة.

قراءة الطلبات

يتم تخصيص معرف كائن طلب فريد لكل طلب يتم إرساله. هذا المعرف يمثل كائن الطلب. يمكن عرض معرف كائن الطلب هذا مع معرف مستخدم المستلم لإنشاء مثيل محدد من الطلب. هذا هو مثيل للطلب الذي تم إرساله إلى مستلم محدد.

على سبيل المثال، عند إرسال طلب، تبدو الاستجابة من مربع حوار طلب اللعبة بالشكل التالي:

{
  request: 'REQUEST_OBJECT_ID'
  to:[array of USER_IDs]
}

إذا بحثت عن معرف كائن الطلب عبر Graph API، فإن الاستجابة التي تستلمها ستختلف قليلًا، وذلك تبعًا لسياق عرض البحث، غير أن الاستجابة ستمثل دومًا كائن الطلب بأكمله.

على سبيل المثال، إذا تم إجراء استعلام إلى http://graph.facebook.com/{REQUEST_OBJECT_ID}?access_token=USER_ACCESS_TOKEN باستخدام رمز وصول المستخدم الخاص للمستلم، فستظهر الاستجابة التالية:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

يُرجى ملاحظة أنه تم عرض الحقلين to و from. مع ذلك، إذا تم استدعاء نقطة النهاية ذاتها باستخدام رمز وصول المرسل أو رمز وصول أحد التطبيقات، فسيعمل فيسبوك على عرض ما يلي:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

للحصول على الطلب الكامل الذي يتضمن المستلم باستخدام رمز وصول أحد التطبيقات، ستحتاج إلى إضافة معرف المستخدم للمستلم بعد حرف الشرطة السفلية "_". لذلك على سبيل المثال، يعمل الاستدعاء إلى https://graph.facebook.com/{REQUEST_OBJECT_ID}_{USER_ID}?access_token={APP_ACCESS_TOKEN} على عرض الآتي:

{
  "id": "REQUEST_OBJECT_ID",
  "application": {
    "name": "APP_DISPLAY_NAME",
    "namespace": "APP_NAMESPACE",
    "id": "APP_ID"
  },
  "to": {
    "name": "RECIPIENT_FULL_NAME",
    "id": "RECIPIENT_USER_ID"
  },
  "from": {
    "name": "SENDER_FULL_NAME",
    "id": "SENDER_USER_ID"
  },
  "message": "ATTACHED_MESSAGE",
  "created_time": "2014-01-17T16:39:00+0000"
}

قراءة كل الطلبات

من أجل قراءة كل الطلبات للمستلم، يمكنك إجراء استعلام للرسم البياني كما هو موضح أدناه باستخدام USER ACCESS TOKEN للمستلم. سيؤدي ذلك إلى عرض قائمة بمعرفات الطلبات لذلك المستخدم في التطبيق.

GET https://graph.facebook.com/me/apprequests?access_token=[USER ACCESS TOKEN]

حذف الطلبات

لا يتم حذف الطلبات تلقائيًا بعد أن يقبلها المستلم. إذ تقع على عاتق المطوّر مسؤولية حذف الطلب بعد قبوله. يجب حذف الطلبات نيابةً عن اللاعبين بمجرد قبولها.

لا يمكنك حذف طلب بالأساليب التالية:

Graph API

إصدار طلب HTTP DELETE إلى request_id المتسلسل:

DELETE https://graph.facebook.com/[{REQUEST_OBJECT_ID}_{USER_ID}]?
      access_token=[USER or APP ACCESS TOKEN]

JavaScript

function deleteRequest(requestId) {
  FB.api(requestId, 'delete', function(response) {
    console.log(response);
  });
}

تتبع الطلبات للإحالات والمكافآت

يمكنك مكافأة مرسل طلب اللعبة استنادًا إلى إجراءات معينة يؤديها المستلم نتيجةً لذلك. على سبيل المثال، لا يمكنك مكافأة اللاعبين لمجرد إرسال الطلبات، ولكن إذا قام المستلم بتثبيت اللعبة والوصول إلى مستوى معين نتيجةً لقبول الطلب، يمكنك في هذه الحالة مكافأة المرسل.

لمكافأة المرسل، يلزمك معرفة الشخص المراد مكافأته. توجد طريقتان لإجراء ذلك:

1. عند إرسال الطلب، قم بتخزين request_id الناتج في الاستجابة من مربع حوار طلب اللعبة ثم قم بمطابقته عند الاستلام لمكافأة المرسل.
2. اقرأ كل الطلبات لأحد اللاعبين عندما يقوم بتشغيل اللعبة، ثم كافئ المرسل استنادًا إلى قيمة id المذكور في الحقل from الخاص بالطلبات. في حالة قيام العديد من الأصدقاء بدعوة لاعب ما، يمكنك اختيار مكافأة المرسل الأول أو كل المرسلين.

API الأصدقاء الذين يمكن دعوتهم

التطويع المحلي

لمساعدتك في توفير أفضل تجربة مستخدم للجمهور على مستوى العالم، يدعم فيسبوك الترجمة لـ requests. قبل ترجمة الطلبات، من المهم معرفة مختلف أنواع الطلبات وكيفية ظهورها. يمكن رؤية الطلبات بالشكل القياسي "Anita sent you a request"، أو إذا تم تحديد زوج إجراء/كائن، بالشكل "Anita asked you for a Life"، أو "Anita sent you a Bomb". هناك أيضًا طلب دور والذي يُعلم الأشخاص بأنه قد حان دورهم في اللعبة ضد صديقهم. كل هذه الأمثلة يراها اللاعبون الذين قاموا بمصادقة اللعبة. إذا لم تكن اللعبة مثبتة لدى المستلم، فسيتم عرض الطلب على شكل دعوة. على سبيل المثال، "Anita invited you to play Friend Smash!". لنلقِ نظرة على كيفية ترجمة كل من هذه الطلبات.

ترجمة الدعوات

تتم ترجمة نص الدعوة تلقائيًا بواسطة فيسبوك، ولا يمكن للمطورين التحكم فيه. تتم ترجمة النص إلى لغة المستلم.

إشعار الدعوة باللغة الإنجليزية

إشعار الدعوة باللغة التايلاندية

يُرجى أن تلاحظ في الأمثلة السابقة أن النص "invited you to play" تتم ترجمته تلقائيًا إلى اللغة الأخرى، وهي التايلاندية في هذه الحالة. تتم ترجمة اسم التطبيق ووصفه في قسم "ترجمة" من إعدادات التطبيق مثل "اسم العرض" و"الوصف"، في المربعات الصفراء أدناه.

ترجمة اسم العرض والوصف للتطبيق

من الممكن أن تظهر التطبيقات كذلك في مركز التطبيقات. في مركز التطبيقات، يتم عرض "رسالة" الطلب. يمكن أن يقوم المطوّر بترجمة الرسالة. في الأمثلة التالية، نص الرسالة هو "Can I have a life to help me through the next level?" بالإنجليزية و"ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า" بالتايلاندية. لا يتم حاليًا عرض النص الأساسي للطلب "Anita sent you a request" في مركز التطبيقات.

الطلب في مركز التطبيقات باللغة الإنجليزية

الطلب في مركز التطبيقات باللغة التايلاندية

ترجمة الرسالة

نظرًا لأنه يتم تمرير الرسالة كمعلمة عند استدعاء مربع حوار الطلب، يمكنك ترجمة الرسالة بالطريقة التي تناسبك قبل استدعاء مربع حوار الطلب وتمرير الرسالة كسلسة مترجمة. إذا أردت تغيير الترجمة بشكل ديناميكي، فينبغي عليك القيام بذلك قبل استدعاء مربع الحوار. يرجع إليك أمر تحديد اللغة التي ترغب في عرضها لأن هذا النص سيكون هو النص ذاته الذي يراه المرسل في معاينة الطلب، ويراه المستلم عند استلام الطلب.

يكتشف كثير من المطوّرين لغة المرسل، ثم يستخدمون ذلك لتحديد اللغة المطلوب استخدامها لنص الرسالة. يفترض هؤلاء المطوّرون أن المرسل والمستلم في أغلب الأحوال يتحدثان اللغة ذاتها. في المثال السابق، يمكنك أن تنظر إلى لغة المرسل وإذا كانت التايلاندية، يمكنك إرسال السلسلة باللغة التايلاندية مباشرةً لنص الرسالة، مثلما يلي:

FB.ui({method: 'apprequests',
  message: 'ช่วยส่งตัวเพิ่มให้หน่อย ต้องใช้ไปเลเวลหน้า'
}, requestCallback);

أفضل الممارسات

إضافة بيانات إلى الطلب

كما ذكرنا في قسم معلمات مربع الحوار أعلاه، يمكنك إضافة حتى 255 حرفًا من البيانات الإضافية لإرسالها مع الطلب. يمكنك استخدام هذه الأداة لنقل معلومات إضافية عن الطلب، أو لإضافة معرف يمكنك استخدامه لاحقًا للبحث عن المعلومات ذات الصلة المخزنة على الخادم.

كمثال، نجد في مشروع عينة لعبة فيسبوك "Friend Smash"، أن اللاعبين يأخذون أدوارهم في المنافسة "لتحطيم" أعلى عدد ممكن من الأصدقاء. عندما يقوم أحد اللاعبين بإرسال تحدي إلى لاعب آخر، عن طريق طلب، يتم استخدام معلمة البيانات لتخزين آخر نقاط أحرزها اللاعب المتحدي. تقوم اللعبة بعد ذلك باستخراج هذه القيمة للاعب المستلم، وتجعلها النقاط المستهدفة للعبة التالية.

فلترة الدعوات

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

يمثل فلتر app_non_users أحد الفلاتر الشائعة المستخدمة عند تنفيذ الدعوات باستخدام مربع حوار طلب اللعبة. يقوم هذا الفلتر بمنع مربع حوار طلب اللعبة من عرض الأشخاص الذين قاموا بتشغيل اللعبة سابقًا. تتمثل الفلاتر الأخرى التي قد تفكر في استخدامها في اللاعبين الذين تم التفاعل معهم مؤخرًا أو لاعبي الألعاب المماثلة التي تتحكم فيها. للاطلاع على قائمة كاملة بالفلاتر المتوفرة، راجع المستند المرجعي مربع حوار طلب اللعبة - المعلمات.

إنشاء آليات التفاعل

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

جعل الكائن قيّمًا بالنسبة إلى اللاعب

عليك أن تعرض شيئًا ذا قيمة للاعب بحيث يمكنه استخدامه في تحسين ممارسته لتشغيل اللعبة أو تجربته الاجتماعية.

تقسيم اللاعبين وعرض الطلبات في سياقها

يمكنك تقييم اللاعبين وتقسيمهم إلى مجموعات عديدة تفيد اللعبة (مثال: اللاعبين الجُدد، اللاعبين المتمتعون بالمهارة، اللاعبون الذين لديهم الكثير من الأصدقاء، اللاعبون المشاركون، إلخ). عليك أن تفكر في أنواع الأشياء التي ستكون مفيدة لهم على مستواهم، وعرض أشياء محددة لكل شريحة منهم.