Payments Lite

نظرة عامة

Payments Lite هي طريقة جديدة لتحديد وإدارة عمليات الشراء داخل تطبيق اللعبة باعتبارها products في لوحة معلومات التطبيق، وتعيين معرف واسم ووصف وسعر وعملة وصورة. يتم بعد ذلك تمرير product ID إلى عملية استدعاء JavaScript لبدء دفق عمليات الدفع بدلاً من عنوان URL لكائن OG Object الذي يطلبه دفق عمليات الدفع بشكل دوري. ويتيح هذا الأمر توفير دفق سلس لإنشاء وتعديل المنتجات دون الحاجة إلى إرسال البيانات إلى المتصفح عبر الخادم.

إنشاء المنتجات

لإنشاء منتج، يجب التنقل إلى Canvas Payments (عمليات الدفع في Canvas) في لوحة معلومات التطبيق لعرض القسم الفرعي Products (المنتجات).

لإنشاء منتج، انقر على الزر Create New Product (إنشاء منتج جديد) في أعلى اليسار. في مربع حوار "Product Details (تفاصيل المنتج)"، أدخل Product ID وTitle وDescription وPrice، وحدد عملة من القائمة المنسدلة، وقم بتحميل صورة بحجم 50 × 50 بيكسل تمثل منتجك.

واجهة API قائمة المنتجات

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

GET https://graph.facebook.com/APP_ID/products

بالمعلمات التالية:

نموذج للاستدعاء والاستجابة:

FB.api(
  '/app/products', 
  'get', 
  function(response) {
    console.log(response);
  }
);

FB.API(
  "app/products",
  HttpMethod.GET,
  this.productCallback // callback that receives a IGraphResult
);

{
  "data": [
    {
      "title": "100 coins lite package",
      "product_id": "payments_lite_test_01",
      "product_type": "managed",
      "description": "Package of 100 coins to test Payments Lite",
      "price": "$1.00",
      "price_amount_cents": 100,
      "price_currency_code": "USD"
    },
    {
      "title": "Friend Smash!",
      "product_id": "480369938658210_premium",
      "product_type": "managed",
      "description": "One time purchase to play game",
      "price": "$0.01",
      "price_amount_cents": 1,
      "price_currency_code": "USD"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUlg1cXRqcnVad05taFRVRlZAZAU2tQdWNSd0FKRDh1TTJMdGd3azVTZA3ZAZAOFgzcXZAaZAlQ1N1VMMmRmZAXpUNG9KX2tsSWhYVlB6Yko2cEotUXZAiRGgzQkFKc0lJLUQzVlJxbHVPampZAS19SWEQ4",
      "after": "QVFIUmRiSGltU1BKQnRqWTRxNkd1WktUTHFKMmxvaEwtV2dSYUtpeDJxQnN0Ri1mZAnF0TG1Ub3oyWnphSExqZAU5qQzNNZAmFrejVnSTlaRVVGMXdSSlNsNE13"
    }
  }
}

استدعاء واجهة المستخدم

بمجرد تحديد المستخدم لأحد المنتجات، يجب مطالبته بإتمام شرائه عن طريق استدعاء مربع الحوار "الدفع". ويمكنك القيام بذلك من خلال وظيفة ui لكائن FB بمجموعة Javascript SDK لفيسبوك.

لاستدعاء مربع الحوار "الدفع"، يجب إدخال كائن JSON كمعلمة أولى بالمفاتيح التالية:

نموذج للرمز البرمجي الذي يتم استخدامه لاستدعاء مربع الحوار:

FB.ui(
  {
    method: 'pay',
    action: 'purchaseiap',
    product_id: 'com.fb.friendsmash.coins.10',
    developer_payload: 'this_is_a_test_payload'
  },
  response => (console.log(response)) // Callback function
);

FB.PayWithProductId(
  "com.fb.friendsmash.coins.10",
  "purchaseiap",
  1,
  null, null, null, null, null,
  this.payCallback  // Callback function that receives an IPayResult
);

بعد اكتمال الدفق، يمكنك التحقق من نتائج المعاملة عن طريق توفير وظيفة استدعاء كمعلمة ثانية في عملية الاستدعاء. سيتم استدعاء هذه الوظيفية باستخدام الكائن الذي يحتوي على معلومات حول المعاملة أو رمز الخطأ والرسالة:

نموذج لاستجابة ناجحة:

{
  app_id: 241431489326925,
  developer_payload: "this_is_a_test_payload",
  payment_id: 860496004080598,
  product_id: "com.fb.friendsmash.coins.10",
  purchase_time: 1473719771,
  purchase_token: "10157567446205226",
  signed_request: "M3fQFj6MlK7WJi597QgCvMlMLh7fl_...",
}

نموذج لاستجابة بها خطأ:

{
  error_code: 1383010, 
  error_message: "User canceled the order."
}

سرد العناصر التي قام اللاعب بشراؤها

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

لسرد العناصر التي قام اللاعب الحالي بشرائها، يمكنك استخدام نقطة نهاية /APP_ID/purchases لتطبيقك مع رمز وصول مستخدم. وتعرض عملية الاستدعاء هذه جميع العناصر التي اشتراها اللاعب الحالي ولم يتم استهلاكها، مع معلومات الشراء المرتبطة بها.

علي سبيل المثال، باستخدام عمليات الاستدعاء التالية:

FB.api(
  '/app/purchases',
  'get',
  {access_token: 'ACCESS_TOKEN'},      // user access token
   payload => {        // callback function
     console.log('purchases payload:');
     console.log(payload);
   }
);

FB.API(
  "/app/purchases?access_token=YOUR_ACCESS_TOKEN",
  HttpMethod.GET,
  this.purchasesCallback // callback that receives a IGraphResult
);

نموذج للاستجابة:

{
  data: [
    {
      app_id: 241431489326925,
      developer_payload: "this_is_a_test_payload",
      payment_id: 860496004080598,
      product_id: "com.fb.friendsmash.coin",
      purchase_time: 1473719771,
      purchase_token: "10157567446205226",
      signed_request: "M3fQFj6MlK7WJi597QgCvMlMLh7fl_...",
    },
    {
      ...
    }
  ],
  paging: {
    cursors: {
      after: "M3fQFj6MlK7WJi597QgCvMlMLh7fl...",
      before: "M3fQFj6MlK7WJi597QgCvMlMLh7...",
    }
  }
}

استهلاك العناصر التي تم شراؤها

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

لاستهلاك عنصر تم شراؤه، يجب استخدام purchase_token المتوفر في عملية استدعاء JavaScript أو في قائمة العناصر التي قام اللاعب بشرائها الموضحة في القسم الأخير. ولتمييز عملية الشراء كعنصر يمكن استهلاكه، يجب استدعاء نقطة نهاية Graph API التالية:

POST	https://graph.facebook.com/PURCHASE_TOKEN/consume

على سبيل المثال، باستخدام Facebook JavaScript SDK:

FB.api(
  '/' + PURCHASE_TOKEN + '/consume',    // Replace the PURCHASE_TOKEN
  'post',
  {access_token: access_token},         // Replace with a user access token
  result => {
    console.log('consuming product', productId, 'with purchase token', purchaseToken);
    console.log('Result:');
    console.log(result);
  }
);

FB.API(
  "/YOUR_PURCHASE_TOKEN/consume?access_token=YOUR_ACCESS_TOKEN",
  HttpMethod.POST,
  this.consumeCallback // callback that receives a IGraphResult
);

نموذج لاستجابة ناجحة:

{
  success: true,
}