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

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

قبل البدء

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

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

• حدِّد أحداث لعبتك في Google Play Console.
• اتّبِع الاقتراحات الواردة في قائمة التحقّق من تسجيل الدخول.

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

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