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

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

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

قبل البدء

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

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

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

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

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

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

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

  • تنشئ "خدمات ألعاب Google Play" القيمة eventId عند تحديد الحدث في 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);
          }
        }
      });
}