رویدادها در بازی های اندروید

پس از منسوخ شدن رابط برنامه‌نویسی کاربردی ورود گوگل (Google Sign-In API)، ما در سال ۲۰۲۶ کیت توسعه نرم‌افزاری بازی‌ها نسخه ۱ (games v1 SDK) را حذف خواهیم کرد. پس از فوریه ۲۰۲۵، شما قادر به انتشار عناوینی که به تازگی با کیت توسعه نرم‌افزاری بازی‌ها نسخه ۱ (games v1 SDK) ادغام شده‌اند، در گوگل پلی نخواهید بود. توصیه می‌کنیم به جای آن از کیت توسعه نرم‌افزاری بازی‌ها نسخه ۲ (games v2 SDK) استفاده کنید.
در حالی که عناوین موجود با بازی‌های قبلی نسخه ۱ ادغام‌شده تا چند سال دیگر به کار خود ادامه می‌دهند، توصیه می‌شود از ژوئن ۲۰۲۵ به نسخه ۲ مهاجرت کنید .
این راهنما برای استفاده از SDK نسخه ۱ سرویس بازی‌های Play Games Services است. برای اطلاعات بیشتر در مورد آخرین نسخه SDK، به مستندات نسخه ۲ مراجعه کنید.

این راهنما به شما نشان می‌دهد که چگونه با استفاده از APIهای رویدادها که توسط سرویس‌های بازی‌های گوگل پلی ارائه می‌شوند، داده‌های گیم‌پلی بازیکنان را برای تجزیه و تحلیل بازی جمع‌آوری کنید. این APIها را می‌توانید در com.google.android.gms.games.event و com.google.android.gms.games پیدا کنید.

قبل از اینکه شروع کنی

اگر قبلاً این کار را نکرده‌اید، مرور مفاهیم بازی رویدادها می‌تواند مفید باشد.

قبل از شروع کدنویسی با استفاده از APIهای رویدادها:

• رویدادهای بازی خود را در کنسول گوگل پلی تعریف کنید.
• توصیه‌های چک‌لیست ورود را دنبال کنید.

کلاینت رویدادها را دریافت کنید

برای شروع استفاده از APIهای رویدادها، بازی شما ابتدا باید یک شیء EventsClient دریافت کند. می‌توانید این کار را با فراخوانی متد Games.getEventsClient() و ارسال activity و GoogleSignInAccount برای بازیکن فعلی انجام دهید. برای یادگیری نحوه بازیابی اطلاعات حساب بازیکن، به بخش ورود به سیستم در بازی‌های اندروید مراجعه کنید.

نکته: کلاس EventsClient از کلاس Task سرویس‌های Google Play برای بازگرداندن نتایج به صورت ناهمگام استفاده می‌کند. برای کسب اطلاعات بیشتر در مورد استفاده از وظایف برای مدیریت کار رشته‌ای، به راهنمای توسعه‌دهنده API وظایف مراجعه کنید.

ارسال رویدادها

شما می‌توانید کدی را در بازی خود اضافه کنید تا هر زمان که رویدادی مورد توجه بازی شما رخ داد، به سرویس‌های بازی‌های گوگل پلی اطلاع دهید.

برای ارسال به‌روزرسانی رویداد، تابع EventsClient.increment() را با مقدار eventId و یک عدد صحیح incrementAmount که برابر یا بزرگتر از 0 است، فراخوانی کنید.

• eventId توسط سرویس‌های بازی‌های گوگل پلی (Google Play Games Services) هنگام تعریف اولیه رویداد در کنسول گوگل پلی ایجاد می‌شود و برای شناسایی منحصر به فرد این رویداد در بازی شما استفاده می‌شود.
• شما می‌توانید از ورودی incrementAmount برای مشخص کردن پیشرفت کمی بازیکن در جهت تکمیل برخی از اهداف خاص بازی استفاده کنید. برای مثال، اگر رویدادی که بازی شما می‌خواهد ردیابی کند «شکست دادن ۵۰۰ هیولای چشم‌بلبلی» باشد، مقدار incrementAmount می‌تواند تعداد هیولاهایی باشد که بازیکن در یک نبرد کشته است.

در اینجا مثالی از نحوه ارسال رویدادی با مقدار افزایش ۱ آورده شده است:

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

بازیابی رویدادها

شما می‌توانید با فراخوانی EventsClient.load() تمام داده‌های رویدادهای ذخیره شده در سرورهای گوگل برای بازی خود را بازیابی کنید. در فراخوانی متد، یک مقدار بولی ارسال کنید تا مشخص شود که آیا سرویس‌های بازی‌های گوگل پلی باید داده‌های ذخیره شده محلی روی دستگاه کاربر را پاک کنند یا خیر.

برای بازیابی داده‌ها برای رویدادهای خاصی که در کنسول گوگل پلی تعریف کرده‌اید، EventsClient.loadByIds() را فراخوانی کنید و آرایه‌ای از شناسه‌های رویداد را در پارامترهای ورودی ارسال کنید.

قطعه کد زیر نشان می‌دهد که چگونه می‌توانید از سرویس‌های بازی‌های گوگل پلی، فهرست تمام رویدادهای بازی خود را درخواست کنید:

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);
          }
        }
      });
}