หน้านี้ได้รับการแปลโดย Cloud Translation API

ลงชื่อเข้าใช้เกม 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

หากต้องการเข้าถึงฟังก์ชันการทำงานของบริการ Google Play Games เกมของคุณจะต้องระบุบัญชีของผู้เล่นที่ลงชื่อเข้าใช้ หากผู้เล่นไม่ได้รับการตรวจสอบสิทธิ์ เกมของคุณอาจพบข้อผิดพลาด เมื่อเรียกใช้ Google Play Games Services API เอกสารนี้อธิบายวิธี ใช้ประสบการณ์การลงชื่อเข้าใช้ที่ราบรื่นในเกม

ใช้การลงชื่อเข้าใช้ของผู้เล่น

คลาส GoogleSignInClient เป็นจุดแรกเข้าหลักในการดึงข้อมูลบัญชีของผู้เล่นที่ลงชื่อเข้าใช้อยู่ในปัจจุบัน และลงชื่อเข้าใช้ผู้เล่นหากผู้เล่นยังไม่ได้ลงชื่อเข้าใช้แอปของคุณในอุปกรณ์

หากต้องการสร้างไคลเอ็นต์การลงชื่อเข้าใช้ ให้ทำตามขั้นตอนต่อไปนี้

สร้างไคลเอ็นต์การลงชื่อเข้าใช้ผ่านออบเจ็กต์ GoogleSignInOptions ดังที่แสดงในข้อมูลโค้ดต่อไปนี้ ใน GoogleSignInOptions.Builder หากต้องการกำหนดค่าการลงชื่อเข้าใช้ คุณต้องระบุ GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN
```
GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
```
หากต้องการใช้ SnapshotsClient ให้เพิ่ม .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS) ลงใน GoogleSignInOptions.Builder ตามที่แสดงในข้อมูลโค้ดต่อไปนี้
```
GoogleSignInOptions  signInOptions =
    new GoogleSignInOptions.Builder(GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN)
        .requestScopes(Games.SCOPE_GAMES_SNAPSHOTS)
        .build();
```
ข้อควรระวัง: อย่าขอขอบเขตหรือข้อมูลโปรไฟล์ Google อื่นๆ เว้นแต่ จะจำเป็นสำหรับกรณีการใช้งานของคุณ ขอบเขตอื่นๆ จะทำให้การลงชื่อเข้าใช้แบบเงียบครั้งแรกไม่สำเร็จ ยกเว้นผู้ใช้ที่ลงชื่อเข้าใช้สำเร็จแล้วในอุปกรณ์อื่น
เรียกใช้เมธอด GoogleSignIn.getClient() และส่งตัวเลือกที่คุณกำหนดค่าไว้ในขั้นตอนก่อนหน้า หากการเรียกสำเร็จ Google Sign-In API จะแสดงอินสแตนซ์ของ GoogleSignInClient

ตรวจสอบว่าผู้เล่นลงชื่อเข้าใช้แล้วหรือไม่

คุณตรวจสอบได้ว่ามีการลงชื่อเข้าใช้บัญชีในอุปกรณ์ปัจจุบันแล้วหรือไม่โดยใช้ GoogleSignIn.getLastSignedInAccount() และตรวจสอบว่าบัญชีนี้มีสิทธิ์ที่จำเป็นแล้วหรือไม่โดยใช้ GoogleSignIn.hasPermissions() หากทั้ง 2 เงื่อนไขเป็นจริง นั่นคือ getLastSignedInAccount() แสดงค่าที่ไม่ใช่ Null และ hasPermissions() แสดง true คุณจะใช้บัญชีที่แสดงจาก getLastSignedInAccount() ได้อย่างปลอดภัยแม้ว่าอุปกรณ์จะออฟไลน์อยู่ก็ตาม

คุณสามารถเรียกใช้ silentSignIn() เพื่อดึงข้อมูลบัญชีของผู้เล่นที่ลงชื่อเข้าใช้ในปัจจุบัน และพยายามลงชื่อเข้าใช้ผู้เล่นโดยไม่ต้องแสดงอินเทอร์เฟซผู้ใช้หากผู้เล่น ลงชื่อเข้าใช้แอปของคุณในอุปกรณ์อื่นเรียบร้อยแล้ว

เมธอด silentSignIn() จะแสดงผล Task<GoogleSignInAccount> เมื่องานเสร็จสมบูรณ์ คุณจะตั้งค่าฟิลด์ GoogleSignInAccount ที่ประกาศไว้ก่อนหน้านี้เป็นบัญชีลงชื่อเข้าใช้ที่งาน ส่งคืนเป็นผลลัพธ์ หรือตั้งค่าเป็น null เพื่อระบุว่าไม่มีผู้ใช้ที่ลงชื่อเข้าใช้

หากการพยายามลงชื่อเข้าใช้แบบเงียบไม่สำเร็จ คุณอาจเลือกส่งเจตนาในการลงชื่อเข้าใช้เพื่อแสดง อินเทอร์เฟซผู้ใช้สำหรับการลงชื่อเข้าใช้ตามที่อธิบายไว้ใน ดำเนินการลงชื่อเข้าใช้แบบอินเทอร์แอกทีฟ

เนื่องจากสถานะของผู้เล่นที่ลงชื่อเข้าใช้อาจเปลี่ยนแปลงได้เมื่อกิจกรรมไม่ได้อยู่ในเบื้องหน้า เราจึง ขอแนะนำให้เรียกใช้ silentSignIn() จากเมธอด onResume() ของกิจกรรม

หากต้องการลงชื่อเข้าใช้แบบเงียบ ให้ทำตามขั้นตอนต่อไปนี้

เรียกใช้เมธอด silentSignIn() ใน GoogleSignInClient เพื่อเริ่มขั้นตอนการลงชื่อเข้าใช้แบบเงียบ การเรียกนี้จะแสดงผลออบเจ็กต์ Task<GoogleSignInAccount> ซึ่งมี GoogleSignInAccount หาก การลงชื่อเข้าใช้แบบเงียบสำเร็จ
จัดการการลงชื่อเข้าใช้เพลเยอร์ที่สำเร็จหรือล้มเหลวโดยการแทนที่ OnCompleteListener
- หากงานการลงชื่อเข้าใช้สำเร็จ ให้รับออบเจ็กต์ GoogleSignInAccount โดยเรียกใช้ getResult()
- หากลงชื่อเข้าใช้ไม่สำเร็จ คุณสามารถส่ง Intent การลงชื่อเข้าใช้เพื่อเปิดตัวขั้นตอนการลงชื่อเข้าใช้แบบอินเทอร์แอกทีฟได้ ดูรายการเครื่องมือฟังการเรียกกลับเพิ่มเติมที่คุณใช้ได้ที่ คู่มือสำหรับนักพัฒนาซอฟต์แวร์ Tasks API และเอกสารอ้างอิง Task API

ข้อมูลโค้ดต่อไปนี้แสดงวิธีที่แอปของคุณจะลงชื่อเข้าใช้แบบเงียบได้

private void signInSilently() {
  GoogleSignInOptions signInOptions = GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN;
  GoogleSignInAccount account = GoogleSignIn.getLastSignedInAccount(this);
  if (GoogleSignIn.hasPermissions(account, signInOptions.getScopeArray())) {
    // Already signed in.
    // The signed in account is stored in the 'account' variable.
    GoogleSignInAccount signedInAccount = account;
  } else {
    // Haven't been signed-in before. Try the silent sign-in first.
    GoogleSignInClient signInClient = GoogleSignIn.getClient(this, signInOptions);
    signInClient
        .silentSignIn()
        .addOnCompleteListener(
            this,
            new OnCompleteListener<GoogleSignInAccount>() {
              @Override
              public void onComplete(@NonNull Task<GoogleSignInAccount> task) {
                if (task.isSuccessful()) {
                  // The signed in account is stored in the task's result.
                  GoogleSignInAccount signedInAccount = task.getResult();
                } else {
                  // Player will need to sign-in explicitly using via UI.
                  // See [sign-in best practices](http://developers.google.com/games/services/checklist) for guidance on how and when to implement Interactive Sign-in,
                  // and [Performing Interactive Sign-in](http://developers.google.com/games/services/android/signin#performing_interactive_sign-in) for details on how to implement
                  // Interactive Sign-in.
                }
              }
            });
  }
}

@Override
protected void onResume() {
  super.onResume();
  signInSilently();
}

หากการพยายามลงชื่อเข้าใช้แบบเงียบล้มเหลว คุณสามารถเรียกใช้ getException() เพื่อ รับ ApiException พร้อมรหัสสถานะแบบละเอียด รหัสสถานะ CommonStatusCodes.SIGN_IN_REQUIRED แสดงว่าเพลเยอร์ต้องดำเนินการอย่างชัดเจนเพื่อลงชื่อเข้าใช้ ในกรณีนี้ แอปของคุณควร เปิดตัวขั้นตอนการลงชื่อเข้าใช้แบบอินเทอร์แอกทีฟตามที่อธิบายไว้ในส่วนถัดไป

หากต้องการลงชื่อเข้าใช้ด้วยการโต้ตอบของผู้เล่น แอปของคุณต้องเปิดใช้ Intent การลงชื่อเข้าใช้ หากสำเร็จ Google Sign-In API จะแสดงอินเทอร์เฟซผู้ใช้ที่แจ้งให้ผู้เล่นป้อนข้อมูลเข้าสู่ระบบ เพื่อลงชื่อเข้าใช้ แนวทางนี้ช่วยลดความซับซ้อนในการพัฒนาแอป เนื่องจากกิจกรรมการลงชื่อเข้าใช้จะจัดการ สถานการณ์ต่างๆ เช่น การต้องอัปเดตบริการ Google Play หรือการแสดงข้อความแจ้งขอความยินยอมในนามของแอป ระบบจะแสดงผลลัพธ์ผ่านการเรียกกลับ onActivityResult

หากต้องการลงชื่อเข้าใช้แบบอินเทอร์แอกทีฟ ให้ทำตามขั้นตอนต่อไปนี้

โทรหา getSigninIntent() ใน GoogleSignInClient เพื่อรับเจตนาในการลงชื่อเข้าใช้ จากนั้นโทรหา startActivity() และส่งเจตนานั้น ข้อมูลโค้ดต่อไปนี้แสดงวิธีที่แอปของคุณสามารถ เปิดตัวขั้นตอนการลงชื่อเข้าใช้แบบอินเทอร์แอกทีฟ
```
private void startSignInIntent() {
  GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
      GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
  Intent intent = signInClient.getSignInIntent();
  startActivityForResult(intent, RC_SIGN_IN);
}
```

ในonActivityResult() การเรียกกลับ ให้จัดการผลลัพธ์จาก Intent ที่ส่งคืน

หากผลการลงชื่อเข้าใช้สำเร็จ ให้รับออบเจ็กต์ GoogleSignInAccount จาก GoogleSignInResult
หากผลการลงชื่อเข้าใช้ไม่สำเร็จ คุณควรจัดการข้อผิดพลาดในการลงชื่อเข้าใช้ (เช่น โดย แสดงข้อความแสดงข้อผิดพลาดในการแจ้งเตือน) ข้อมูลโค้ดต่อไปนี้แสดงวิธีที่แอปจัดการผลการลงชื่อเข้าใช้ของผู้เล่น

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == RC_SIGN_IN) {
    GoogleSignInResult result = Auth.GoogleSignInApi.getSignInResultFromIntent(data);
    if (result.isSuccess()) {
      // The signed in account is stored in the result.
      GoogleSignInAccount signedInAccount = result.getSignInAccount();
    } else {
      String message = result.getStatus().getStatusMessage();
      if (message == null || message.isEmpty()) {
        message = getString(R.string.signin_other_error);
      }
      new AlertDialog.Builder(this).setMessage(message)
          .setNeutralButton(android.R.string.ok, null).show();
    }
  }
}

เรียกข้อมูลผู้เล่น

GoogleSignInAccount ที่ Google Sign-In API แสดงผลจะไม่มีข้อมูลผู้เล่น หากเกมใช้ข้อมูลผู้เล่น เช่น ชื่อที่แสดงของผู้เล่นและรหัสผู้เล่น คุณสามารถทำตามขั้นตอนต่อไปนี้เพื่อดึงข้อมูลนี้

รับออบเจ็กต์ PlayersClient โดยเรียกใช้เมธอด getPlayersClient() และส่ง GoogleSignInAccount เป็นพารามิเตอร์
ใช้วิธีการ PlayersClient เพื่อโหลดออบเจ็กต์ Player ที่มีข้อมูลของผู้เล่นแบบไม่พร้อมกัน เช่น คุณสามารถเรียกใช้ getCurrentPlayer() เพื่อโหลดผู้เล่นที่ลงชื่อเข้าใช้ในปัจจุบัน หากงานส่งคืน ApiException ที่มีรหัสสถานะ เป็น SIGN_IN_REQUIRED แสดงว่าต้องมีการตรวจสอบสิทธิ์ผู้เล่นอีกครั้ง โดยโทรหา GoogleSignInClient.getSignInIntent() เพื่อลงชื่อเข้าใช้ในเพลเยอร์แบบอินเทอร์แอกทีฟ
หากงานแสดงผลออบเจ็กต์ Player สำเร็จ คุณจะเรียกใช้เมธอดของออบเจ็กต์ Player เพื่อดึงรายละเอียดผู้เล่นที่เฉพาะเจาะจงได้ (เช่น getDisplayName() หรือ getPlayerId()

หากต้องการระบุปุ่มลงชื่อเข้าใช้ด้วยบัญชี Google มาตรฐานในเกม คุณสามารถใช้วิธีใดวิธีหนึ่งต่อไปนี้

รวม com.google.android.gms.common.SignInButton ในเลย์เอาต์กิจกรรมหลัก หรือ
ออกแบบปุ่มลงชื่อเข้าใช้ที่กำหนดเองตามหลักเกณฑ์การสร้างแบรนด์ Google Sign-In

เมื่อผู้ใช้คลิกปุ่มลงชื่อเข้าใช้ เกมของคุณควรเริ่มกระบวนการลงชื่อเข้าใช้โดยการส่ง Intent การลงชื่อเข้าใช้ ตามที่อธิบายไว้ในดำเนินการลงชื่อเข้าใช้แบบอินเทอร์แอกทีฟ

ข้อมูลโค้ดนี้แสดงวิธีเพิ่มปุ่มลงชื่อเข้าใช้ในเมธอด onCreate() สำหรับกิจกรรม

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_sign_in);
  findViewById(R.id.sign_in_button).setOnClickListener(this);
  findViewById(R.id.sign_out_button).setOnClickListener(this);
}

ข้อมูลโค้ดต่อไปนี้แสดงวิธีส่ง Intent การลงชื่อเข้าใช้เมื่อผู้ใช้คลิกปุ่ม ลงชื่อเข้าใช้

@Override
public void onClick(View view) {
  if (view.getId() == R.id.sign_in_button) {
    // start the asynchronous sign in flow
    startSignInIntent();
  } else if (view.getId() == R.id.sign_out_button) {
    // sign out.
    signOut();
    // show sign-in button, hide the sign-out button
    findViewById(R.id.sign_in_button).setVisibility(View.VISIBLE);
    findViewById(R.id.sign_out_button).setVisibility(View.GONE);
  }
}

แสดงป๊อปอัปเกม

คุณแสดงมุมมองป๊อปอัปในเกมได้โดยใช้คลาส GamesClient เช่น เกมของคุณ สามารถแสดงป๊อปอัป "ยินดีต้อนรับกลับมา" หรือ "ปลดล็อกรางวัลพิเศษแล้ว" หากต้องการอนุญาตให้บริการเกมของ Google Play เปิดป๊อปอัปในมุมมองในเกม ให้เรียกใช้เมธอด setViewForPopups() คุณปรับแต่งตำแหน่งที่ป๊อปอัปจะปรากฏบนหน้าจอได้โดยเรียกใช้ setGravityForPopups()

ให้ผู้เล่นออกจากระบบ

การออกจากระบบทำได้โดยการเรียกใช้เมธอด signOut() ใน GoogleSignInClient

private void signOut() {
  GoogleSignInClient signInClient = GoogleSignIn.getClient(this,
      GoogleSignInOptions.DEFAULT_GAMES_SIGN_IN);
  signInClient.signOut().addOnCompleteListener(this,
      new OnCompleteListener<Void>() {
        @Override
        public void onComplete(@NonNull Task<Void> task) {
          // at this point, the user is signed out.
        }
      });
}