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

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

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

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

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

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

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

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

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

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

  • eventId توسط سرویس‌های بازی‌های پلی (Play Games Services) هنگام تعریف اولیه رویداد در کنسول گوگل پلی ایجاد می‌شود و برای شناسایی منحصر به فرد این رویداد در بازی شما استفاده می‌شود.

  • شما می‌توانید از ورودی incrementAmount برای مشخص کردن پیشرفت کمی بازیکن در جهت تکمیل برخی از اهداف خاص بازی استفاده کنید. برای مثال، اگر رویدادی که بازی شما می‌خواهد ردیابی کند «شکست دادن ۵۰۰ هیولای چشم‌بلبلی» باشد، مقدار incrementAmount می‌تواند تعداد هیولاهایی باشد که بازیکن در یک نبرد کشته است.

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

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

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

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

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

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

public void loadEvents() {
  PlayGames.getEventsClient(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);
          }
        }
      });
}