ليدربورد

يوضّح لك هذا الدليل كيفية استخدام واجهات برمجة التطبيقات للوحات الصدارة في حزمة تطوير البرامج (SDK) الخاصة بـ "خدمات ألعاب Play" بلغة ++C لإنشاء لوحات صدارة مرئية وتسجيل نتيجة اللاعب ومقارنتها بنتيجة اللاعب من جلسات اللعبة السابقة. يمكن العثور على واجهات برمجة التطبيقات في LeaderboardsClient.

قبل البدء

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

قبل البدء في كتابة الرموز البرمجية باستخدام واجهات برمجة التطبيقات للوحات الصدارة، يجب:

الحصول على عميل لوحات الصدارة

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

تعديل نتيجة اللاعب

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

// Callback function to handle the result of submitting the score
void OnScoreSubmitted(PgsStatusCode status_code,
                      PgsScoreSubmissionData* score_submission_data,
                      void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS) {
    // Score submitted successfully
    // You can inspect score_submission_data for details
    // Remember to release the data when done:
    PgsScoreSubmissionData_Release(score_submission_data);
  } else {
    // Handle error
  }
}

// Function to submit the score
void SubmitScore(PgsLeaderboardsClient* client, const char* leaderboard_id, int64_t score) {
  const char* score_tag = NULL; // Optional tag

  PgsLeaderboardsClient_submitScoreImmediate(
      client,
      leaderboard_id,
      score,
      score_tag,
      OnScoreSubmitted,
      NULL // user_data - optional context pointer
  );
}

// Example usage:
// Assuming 'my_leaderboard_id' is defined elsewhere, e.g., fetched from resources
// SubmitScore(leaderboards_client, my_leaderboard_id, 1337);

من أفضل الممارسات إدارة أرقام تعريف لوحات الصدارة كقيم ثابتة أو موارد ضمن رمز ++C.

عرض لوحة صدارة

لعرض واجهة مستخدم لوحة الصدارة التلقائية للوحة صدارة معيّنة، استدعِ PgsLeaderboardsClient_showLeaderboardUI. تتطلّب هذه الدالة معرّف العميل والنشاط ورقم تعريف لوحة الصدارة والفترة الزمنية والمجموعة ودالة معاودة الاتصال.

// Callback function to handle the result of showing the UI
void OnShowLeaderboardUI(PgsStatusCode status_code, bool success, void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS && success) {
    // UI was shown successfully
  } else {
    // Handle error or failure to show UI
  }
}

// Function to show a specific leaderboard UI
void ShowLeaderboard(PgsLeaderboardsClient* client, jobject activity, const char* leaderboard_id) {
  PgsLeaderboardsClient_showLeaderboardUI(
      client,
      activity,
      leaderboard_id,
      PGS_LEADERBOARD_TIME_SPAN_ALL_TIME, // Or PGS_LEADERBOARD_TIME_SPAN_DAILY, PGS_LEADERBOARD_TIME_SPAN_WEEKLY
      PGS_LEADERBOARD_COLLECTION_PUBLIC,  // Or PGS_LEADERBOARD_COLLECTION_FRIENDS
      OnShowLeaderboardUI,
      NULL // user_data - optional context pointer
  );
}

// Example usage:
// ShowLeaderboard(leaderboards_client, android_activity, my_leaderboard_id);

تعرض هذه الدالة واجهة المستخدم. يوفّر كائن activity السياق لعرض واجهة المستخدم.