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

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

قبل البدء

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

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

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

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

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

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

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

  • يتم إنشاء eventId بواسطة "خدمات ألعاب Play" عند تحديد الحدث لأول مرة في 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);
          }
        }
      });
}