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

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

قبل البدء

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

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

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

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

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

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

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

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

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

• يتم إنشاء eventId من خلال "خدمات ألعاب Play" عند تحديد الحدث للمرة الأولى في Google Play Console، ويتم استخدامه لتحديد هذا الحدث في لعبتك بشكل فريد.
• يمكنك استخدام الإدخال incrementAmount لتحديد مستوى تقدّم اللاعب من أجل تحقيق هدف متعلق باللعبة. على سبيل المثال، إذا كان الحدث الذي تريد لعبتك تتبُّعه هو "Defeat 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);
          }
        }
      });
}