الأحداث في ألعاب Android

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

قبل البدء

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

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

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

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

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

يمكنك إضافة شفرة في لعبتك لإشعار خدمات ألعاب Google Play متى حدث حدث هام للعبتك.

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

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

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

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

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

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

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

يعرض المقتطف التالي كيفية الاستعلام عن خدمات ألعاب Google 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);
          }
        }
      });
}