กิจกรรมในเกม Android

หลังจากเลิกใช้งาน API ของ Google Sign-In แล้ว เราจะนำ SDK v1 ของเกมออกในปี 2026 หลังจากเดือนกุมภาพันธ์ 2025 คุณจะเผยแพร่ เกมที่เพิ่งผสานรวมกับ SDK v1 ของ Games ใน Google Play ไม่ได้ เราขอแนะนำให้ใช้ SDK v2 ของ Games แทน
แม้ว่าเกมที่มีอยู่ซึ่งผสานรวมกับ v1 ก่อนหน้านี้จะยังทำงานได้อีก 2-3 ปี แต่เราขอแนะนำให้คุณย้ายข้อมูลไปยัง v2 ตั้งแต่เดือนมิถุนายน 2025 เป็นต้นไป
คู่มือนี้มีไว้สำหรับการใช้ SDK บริการเกมของ Play v1 ดูข้อมูล เกี่ยวกับ SDK เวอร์ชันล่าสุดได้ที่ เอกสารประกอบ v2

คู่มือนี้จะแสดงวิธีรวบรวมข้อมูลการเล่นเกมของผู้เล่นเพื่อใช้ในการวิเคราะห์เกมโดยใช้ Events API ที่บริการเกมของ Google Play มีให้ คุณจะพบ API ได้ใน com.google.android.gms.games.event และ com.google.android.gms.games

ก่อนเริ่มต้น

หากยังไม่ได้ดำเนินการ คุณอาจต้องดูแนวคิดเกี่ยวกับเกมกิจกรรม

ก่อนเริ่มเขียนโค้ดโดยใช้ API เหตุการณ์ ให้ทำดังนี้

กำหนดเหตุการณ์สำหรับ เกมใน Google Play Console
ทำตามคำแนะนำในรายการตรวจสอบการลงชื่อเข้าใช้

รับไคลเอ็นต์เหตุการณ์

หากต้องการเริ่มใช้ API เหตุการณ์ เกมของคุณต้องได้รับออบเจ็กต์ 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);
          }
        }
      });
}