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

بعد إيقاف واجهة برمجة التطبيقات تسجيل الدخول باستخدام Google نهائيًا، سنزيل الإصدار v1 من حزمة تطوير البرامج (SDK) للألعاب في عام 2026. بعد فبراير 2025، لن يكون بإمكانك نشر الألعاب التي تم دمجها حديثًا مع الإصدار v1 من حزمة SDK للألعاب على Google Play. ننصحك باستخدام الإصدار v2 من حزمة SDK للألعاب بدلاً من ذلك.
مع أنّ التطبيقات الحالية التي تتضمّن عمليات الدمج السابقة للإصدار 1 من "خدمات ألعاب Google Play" ستستمر في العمل لعدّة سنوات، ننصحك بنقل البيانات إلى الإصدار 2 بدءًا من يونيو 2025.
هذا الدليل مخصّص لاستخدام الإصدار 1 من حزمة تطوير البرامج (SDK) الخاصة بـ "خدمات ألعاب Play". للحصول على معلومات حول أحدث إصدار من حزمة SDK، يُرجى الاطّلاع على مستندات الإصدار 2.

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

قبل البدء

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

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

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

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

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

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

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

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

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

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

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

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

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

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

public void loadEvents() {
  Games.getEventsClient(this, GoogleSignIn.getLastSignedInAccount(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);
          }
        }
      });
}