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

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

قبل البدء

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

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

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

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

الحصول على برنامج الأحداث

لبدء استخدام واجهات برمجة التطبيقات الخاصة بالأحداث، يجب أن تحصل لعبتك أولاً على الكائن 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);
          }
        }
      });
}