فعاليات ألعاب Android

يوضّح لك هذا الدليل كيفية جمع بيانات أسلوب اللعب لدى اللاعبين لأغراض إحصاءات الألعاب باستخدام واجهات برمجة تطبيقات الأحداث التي تقدّمها "خدمات ألعاب Play". يمكن العثور على واجهات برمجة التطبيقات في الحزم com.google.android.gms.games.event وcom.google.android.gms.games.

قبل البدء

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

قبل بدء الترميز باستخدام واجهات برمجة تطبيقات الأحداث:

• حدِّد أحداث لعبتك في Google Play Console.

• اتّبِع الاقتراحات الواردة في قائمة التحقّق من تسجيل الدخول.

الحصول على عميل الأحداث

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

إرسال الأحداث

يمكنك إضافة رمز في لعبتك لإرسال إشعار إلى "خدمات ألعاب Play" عند وقوع حدث يمثّل اهتمامًا للعبة.

لإرسال تعديل حدث، استخدِم الدالة EventsClient.increment() مع القيمة eventId وعدد صحيح incrementAmount يساوي أو أكبر من 0.

• تنشئ "خدمات ألعاب Play" القيمة eventId عند تحديد الحدث لأول مرة في Google Play Console، ويتم استخدامها لتحديد هوية هذا الحدث بشكل فريد في لعبتك.

• يمكنك استخدام الإدخال incrementAmount لتحديد التقدّم الكمي لللاعب نحو إكمال بعض الأهداف الخاصة باللعبة. على سبيل المثال، إذا كان الحدث الذي تريد لعبتك تتبُّعه هو "هزيمة 500 وحش ذي عيون حشرات"، يمكن أن تكون قيمة incrementAmount هي عدد الوحوش التي قتلها اللاعب في معركة واحدة.

في ما يلي مثال على كيفية إرسال حدث بقيمة متزايدة تبلغ 1:

public void submitEvent(String eventId) {
  PlayGames.getEventsClient(this)
      .increment(eventId, 1);
}

استرداد الأحداث

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

لاسترداد بيانات عن أحداث معيّنة حدّدتها في Google Play Console، يمكنك استدعاء دالة EventsClient.loadByIds() وإدخال صفيف من أرقام تعريف الأحداث في مَعلمات الإدخال.

يوضّح المقتطف التالي كيفية طلب بيانات من "خدمات ألعاب Play" للحصول على قائمة بجميع أحداث لعبتك:

public void loadEvents() {
  PlayGames.getEventsClient(this)
      .load(true)
      .addOnCompleteListener(new OnCompleteListener<AnnotatedData<EventBuffer>>() {
        @Override
        public void onComplete(@NonNull Task<AnnotatedData<EventBuffer>> task) {
          if (task.isSuccessful()) {
            // Process all the events.
            for (Event event : task.getResult().get()) {
              Log.d(TAG, "loaded event " + event.getName());
            }
          } else {
            // Handle Error
            Exception exception = task.getException();
            int statusCode = CommonStatusCodes.DEVELOPER_ERROR;
            if (exception instanceof ApiException) {
              ApiException apiException = (ApiException) exception;
              statusCode = apiException.getStatusCode();
            }
            showError(statusCode);
          }
        }
      });
}