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

بعد إيقاف Google Sign-In API نهائيًا، سنزيل الإصدار v1 من حزمة تطوير البرامج (SDK) الخاصة بـ "خدمات ألعاب Play". في عام 2026. بعد فبراير 2025، لن يكون بإمكانك نشر الألعاب التي تتكامل مع الإصدار v2 من حزمة SDK الخاصة بـ "خدمات ألعاب Play". ننصحك باستخدام الإصدار v2 حزمة SDK الخاصة بـ "خدمات ألعاب Play". بدلاً من ذلك.
مع أنّ التطبيقات الحالية التي تتكامل مع الإصدار v1 من حزمة SDK الخاصة بـ "خدمات ألعاب Play" ستستمر في العمل لعدّة سنوات، ننصحك بالانتقال إلى الإصدار v2 بدءًا من يونيو 2025.
هذا الدليل مخصّص لاستخدام الإصدار v1 من حزمة 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);
          }
        }
      });
}