ผสานรวม PGS Recall API ภายในเกม

หน้านี้อธิบายวิธีใช้ Recall API ภายในเกม โดยจะเริ่มจากการตั้งค่าเซิร์ฟเวอร์และไคลเอ็นต์เกมให้รองรับ API จากนั้นจะอธิบายวิธีจัดเก็บและเรียกโทเค็น

การตั้งค่าเซิร์ฟเวอร์เกม

ตั้งค่าเซิร์ฟเวอร์เกมเพื่อเรียกใช้ Recall API ไปยังเซิร์ฟเวอร์ของ Google

1. ตั้งค่าโปรเจ็กต์บริการเกมของ Play

(หากยังไม่ได้ดำเนินการ) ทำตามวิธีการในตั้งค่าบริการเกมของ Google Play

หมายเหตุ: โทเค็นการเรียกคืนและลักษณะตัวตนพร้อมให้บริการในแต่ละโปรเจ็กต์ PGS ซึ่งหมายความว่าระบบจะจัดเก็บโทเค็นและอวตารตามโปรเจ็กต์ PGS แต่ละโปรเจ็กต์ และสำหรับโปรเจ็กต์ PGS แยกต่างหาก จะมีการรวบรวมลิงก์แยกต่างหากระหว่างโปรไฟล์ PGS กับอวตาร เราขอแนะนำให้คุณอ่านเอกสารนี้เมื่อพิจารณาวิธีตั้งค่าโปรเจ็กต์ PGS

2. สร้างบัญชีบริการสำหรับเกม

ทำตามวิธีการสร้างบัญชีบริการ ในตอนท้าย คุณควรมีไฟล์ JSON ที่มีข้อมูลเข้าสู่ระบบของบัญชีบริการ

หมายเหตุ: Recall API เป็น API แบบเซิร์ฟเวอร์ถึงเซิร์ฟเวอร์ ด้วยเหตุนี้ Recall API จึงใช้บัญชีบริการเพื่อตรวจสอบสิทธิ์เซิร์ฟเวอร์เกม ไม่ใช่ OAuth แบบ 3 ทางปกติ ซึ่ง API ของเกมอื่นๆ ใช้เพื่อตรวจสอบสิทธิ์ทั้งเซิร์ฟเวอร์เกมและผู้ใช้ปลายทาง

3. ดาวน์โหลดไลบรารี Java ฝั่งเซิร์ฟเวอร์สำหรับ PlayGamesServices

ดาวน์โหลดไลบรารี google-api-services-games เวอร์ชันล่าสุด แล้วอัปโหลดไปยังเซิร์ฟเวอร์

4. เตรียมข้อมูลเข้าสู่ระบบสำหรับการเรียก Recall API

ดูข้อมูลเพิ่มเติมได้ที่การเตรียมพร้อมสำหรับการเรียก API ที่ได้รับอนุญาต

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.games.Games;
import com.google.api.services.games.GamesScopes;

// ...

GoogleCredential credential =
  GoogleCredential.fromStream(new FileInputStream("<credentials>.json"))
    .createScoped(Collections.singleton(GamesScopes.ANDROIDPUBLISHER));

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

การตั้งค่าไคลเอ็นต์เกม

ตั้งค่าไคลเอ็นต์เกมเพื่อดึงรหัสเซสชันการเรียกคืนที่เซิร์ฟเวอร์ใช้ เพื่อสื่อสารกับเซิร์ฟเวอร์ของ Google

Java SDK

ตั้งค่า Java SDK ภายในไคลเอ็นต์ และ ตรวจสอบว่าได้รวม com.google.android.gms:play-services-games-v2:19.0.0 และ com.google.android.gms:play-services-tasks:18.0.2 ขึ้นไปไว้ใน ไฟล์ Gradle

หากต้องการสื่อสารกับเซิร์ฟเวอร์ของ Google ด้วยข้อมูลที่ถูกต้อง คุณต้อง ขอรหัสเซสชัน Recall จาก SDK ไคลเอ็นต์ ซึ่งคุณจะส่งไปยังเซิร์ฟเวอร์ของเกม

Kotlin

PlayGames.getRecallClient(getActivity())
                .requestRecallAccess()
                .addOnSuccessListener { recallAccess -> val recallSessionId: String = recallAccess.getSessionId() }
                // Send the recallSessionId to your game server

Java

PlayGames.getRecallClient(getActivity())
  .requestRecallAccess()
  .addOnSuccessListener(
    recallAccess -> {
      String recallSessionId = recallAccess.getSessionId();
      // Send the recallSessionId to your game server
    });

Unity SDK

หากยังไม่ได้ดำเนินการ ให้ตั้งค่า Unity SDK ภายในไคลเอ็นต์

หากต้องการสื่อสารกับเซิร์ฟเวอร์ของ Google ด้วยข้อมูลที่ถูกต้อง คุณต้องขอรหัสเซสชัน Recall จาก SDK ไคลเอ็นต์ แล้วส่งไปยังเซิร์ฟเวอร์ของเกม

PlayGamesPlatform.Instance.RequestRecallAccess(
    recallAccess => {
        string recallSessionId = recallAccess.sessionId;
        // Send the recallSessionId to your game server
    });

ใช้ Recall API ภายในเซิร์ฟเวอร์เกม

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

จัดเก็บโทเค็น

คุณจัดเก็บลักษณะตัวตนและโทเค็นเกมของผู้ใช้ได้โดยใช้LinkPersonaRequest ออบเจ็กต์ คุณต้องใช้ GoogleCredential เพื่อเรียกใช้ Google APIs (ดูบริบทได้ที่การเรียกใช้ Google APIs ) โปรดทราบว่าตามข้อจำกัดแบบ 1:1 คุณจะลิงก์ลักษณะตัวตนได้ครั้งละ 1 รายการกับโปรไฟล์ PGS 1 รายการเท่านั้น (และในทางกลับกัน) คุณควรตั้งค่านโยบายการแก้ปัญหา ในกรณีที่โปรไฟล์ PGS นี้ลิงก์กับลักษณะตัวตนอื่นอยู่แล้ว

คุณอาจเลือกตั้งค่า TTL ในโทเค็นได้ (ไม่บังคับ) ซึ่งจะประกาศระยะเวลาที่โทเค็นใช้งานได้โดยใช้ออบเจ็กต์ระยะเวลา คุณเลือกตั้งค่านี้ได้โดยใช้ SetTtl() (ดังที่แสดงด้านล่าง) ซึ่งจะตั้งค่า วันที่หมดอายุจากระยะเวลาที่ระบุในเมธอด หรือ setExpireTime() ซึ่งจะช่วยให้คุณตั้งเวลาที่แน่นอนเมื่อโทเค็นหมดอายุได้

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

ระบบจะจัดเก็บโทเค็นได้เพียง 1 รายการต่อตัวตนต่อผู้เล่นในเวลาที่กำหนด การพยายาม จัดเก็บโทเค็นอื่นที่มีลักษณะตัวตนเดียวกันจะเขียนทับโทเค็นเดิม

หมายเหตุ: คีย์การเข้ารหัสที่ใช้สำหรับการเข้ารหัสโทเค็นไม่ควรซ้ำกันสำหรับแต่ละแอปพลิเคชัน หากมีการโอนเกมไปยังนักพัฒนาแอปรายอื่น คุณจะต้องส่งต่อคีย์การเข้ารหัส ให้เจ้าของใหม่ ระบบจะถอดรหัสโทเค็น Recall ไม่ได้หากไม่มี คีย์การเข้ารหัสเดิม

หมายเหตุ: โทเค็นที่สร้างขึ้นสำหรับผู้ใช้ที่ไม่มีโปรไฟล์จะมี TTL เริ่มต้นเป็น 30 วัน หรือสำหรับผู้ใช้ที่มีโปรไฟล์ PGS โทเค็นจะไม่มี TTL เริ่มต้น

import com.google.api.services.games.Games.Recall.LinkPersona;
import com.google.api.services.games.model.LinkPersonaRequest;
import com.google.api.services.games.model.LinkPersonaResponse;
import com.google.protobuf.util.Durations;

// ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

String recallSessionId = ... // recallSessionID from game client
String persona = ... // encrypted opaque string, stable for in-game account
String token = ... // encrypted opaque string encoding the progress line

LinkPersonaRequest linkPersonaRequest =
  LinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    .setToken(token)
    .setCardinalityConstraint(ONE_PERSONA_TO_ONE_PLAYER)
    .setConflictingLinksResolutionPolicy(CREATE_NEW_LINK)
    .setTtl(Durations.fromDays(7)) // Optionally set TTL for token
    .build();

LinkPersonaResponse linkPersonaResponse =
  gamesApi.recall().linkPersona(linkPersonaRequest).execute();

if (linkPersonaResponse.getState() == LINK_CREATED) {
  // success
}

เรียกข้อมูลโทเค็น

คุณมี 3 ตัวเลือกในการดึงโทเค็นตามความต้องการของเกม คุณสามารถ ขอสิ่งต่อไปนี้ได้

• โทเค็นที่เชื่อมโยงกับเกมปัจจุบัน รวมถึงโทเค็นการเรียกคืนที่กำหนดขอบเขตไว้ที่เกม
• โทเค็นล่าสุดที่จัดเก็บไว้ในเกมทั้งหมดที่เป็นของบัญชีนักพัฒนาแอป
• รายการเกมที่เป็นของบัญชีนักพัฒนาแอป รวมถึงโทเค็นการเรียกคืนทั้งหมด ที่เชื่อมโยงกับแต่ละเกม

หมายเหตุ: เมื่อคุณขอโทเค็นการเรียกคืน API จะไม่แสดงผลสตริงที่ แสดงถึงลักษณะตัวตน

โทเค็นการเรียกคืนข้อมูลที่กำหนดขอบเขตเป็นเกม

หากต้องการเรียกโทเค็นการเรียกคืนจากเกมปัจจุบัน ให้รับ recallSessionId จากไคลเอ็นต์และส่งไปยัง API retrieveTokens ดังนี้

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrievePlayerTokensResponse;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrievePlayerTokensResponse retrievePlayerTokensResponse =
  gamesApi.recall().retrieveTokens(recallSessionId).execute();

for (RecallToken recallToken : retrievePlayerTokensResponse.getTokens()) {
  String token recallToken.getToken();
  // Same string as was written in LinkPersona call
  // decrypt and recover in-game account
}

โทเค็นการเรียกคืนล่าสุดในเกมทั้งหมดที่บัญชีนักพัฒนาแอปเป็นเจ้าของ

หากต้องการดึงโทเค็นล่าสุดที่จัดเก็บไว้ในเกมทั้งหมดที่บัญชีนักพัฒนาแอปเป็นเจ้าของใน Google Play Console คุณต้องรับ recallSessionId จากไคลเอ็นต์และส่งไปยัง lastTokenFromAllDeveloperGames API ดังที่แสดงในข้อมูลโค้ดต่อไปนี้ คุณตรวจสอบรหัสแอปพลิเคชันที่เชื่อมโยง กับโทเค็นนี้ได้ในส่วนหนึ่งของการตอบกลับ

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveDeveloperGamesLastPlayerTokenResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

RetrieveDeveloperGamesLastPlayerTokenResponse response =
        gamesApi.recall().lastTokenFromAllDeveloperGames(recallSessionId)
        .execute();

if (response.hasGamePlayerToken()) {
    GamePlayerToken gamePlayerToken = response.getGamePlayerToken();

    // The ID of the application that the token is associated with.
    String applicationId = gamePlayerToken.getApplicationId();

    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

โทเค็นการเรียกคืนทั้งหมดในรายการเกมที่กำหนดซึ่งบัญชีนักพัฒนาแอปเป็นเจ้าของ

หากต้องการดึงโทเค็นทั้งหมดที่เชื่อมโยงกับรายการเกมซึ่งเป็นของบัญชีนักพัฒนาแอปของคุณใน Google Play Console ให้รับ recallSessionId จากไคลเอ็นต์แล้วส่งไปยัง gamesPlayerTokens API ระบุ รายการรหัสแอปพลิเคชัน

import com.google.api.services.games.Games;
import com.google.api.services.games.model.RetrieveGamesPlayerTokensResponse;
import com.google.api.services.games.model.GamePlayerToken;
import com.google.api.services.games.model.RecallToken;

// ...

String recallSessionId = ... // recallSessionID from game client

// Application IDs for which you would like to retrieve the recall tokens.
List<String> applicationIds = ...

RetrieveGamesPlayerTokensResponse response =
gamesApiClient
        .recall()
        .gamesPlayerTokens(recallSessionId)
        .setApplicationIds(applicationIds)
        .execute();

for (GamePlayerToken gamePlayerToken : response.getGamePlayerTokens()) {
    // The ID of the application that the token is associated with.
    String applicationId  = gamePlayerToken.getApplicationId();


    // Same string as was written in LinkPersona call.
    RecallToken recallToken = gamePlayerToken.getRecallToken();

    // Decrypt and recover in-game account.
}

ลบโทเค็นการเรียกคืน

หากจำเป็น คุณยังลบโทเค็นการเรียกคืนได้ด้วยการเรียกใช้ต่อไปนี้

import com.google.api.services.games.Games;
import com.google.api.services.games.model.UnlinkPersonaRequest;
import com.google.api.services.games.model.UnlinkPersonaResponse;

// ...

String recallSessionId = ...
String persona = ...
String token = ...

Games gamesApi =
    new Games.Builder(httpTransport, JSON_FACTORY, credential).build();

UnlinkPersonaRequest unlinkPersonaRequest =
  UnlinkPersonaRequest.newBuilder()
    .setSessionId(recallSessionId)
    .setPersona(persona)
    // .setToken(token) - alternatively set token, but not both
    .build();

UnlinkPersonaResponse unlinkPersonaResponse =
  gamesApi.recall().unlinkPersona(unlinkPersonaRequest).execute();

boolean unlinked = unlinkPersonaResponse.isUnlinked();

เปิดใช้โหมดไม่มีโปรไฟล์

คุณเปิดใช้ฟังก์ชันการทำงานของ Recall API แบบจำกัด สำหรับผู้ใช้ที่ไม่มีโปรไฟล์ PGS ได้โดยทำตามขั้นตอนต่อไปนี้

1. เปิดใช้การเรียกคืนแบบไม่มีโปรไฟล์สำหรับโปรเจ็กต์เกม PGS ใน Play Developer Console
2. โปรดอ่านข้อกำหนดเพิ่มเติมที่อธิบายไว้ในส่วนนี้
3. เพิ่มแท็กข้อมูลเมตาต่อไปนี้ลงใน app manifest

<meta-data
  android:name="com.google.android.gms.games.PROFILELESS_RECALL_ENABLED"
  android:value="true" />

ข้อกำหนดเพิ่มเติม

นอกเหนือจากการอยู่ภายใต้ข้อกำหนดในการให้บริการของบริการเกมของ Play แล้ว คุณยังยอมรับว่าหาก คุณใช้ Recall API สำหรับผู้ใช้ที่ไม่มีโปรไฟล์ PGS ซึ่งจะช่วยให้แชร์ ข้อมูลของผู้ใช้ปลายทางกับ Google ได้โดยที่ผู้ใช้ไม่ต้องมีโปรไฟล์บริการเกมของ Play คุณจะต้องแจ้งให้ผู้ใช้ปลายทางทราบก่อนที่จะแชร์ข้อมูลดังกล่าวกับ Google โดยแจ้งให้ทราบถึงสิ่งต่อไปนี้

1. การแชร์ข้อมูลกับ Google เพื่อเปิดใช้ฟีเจอร์การลิงก์บัญชี Play Games
2. ความพร้อมใช้งานของการตั้งค่าเพื่อจัดการการแชร์ดังกล่าว เช่น การตั้งค่าผ่าน การตั้งค่า Play Games
3. การประมวลผลข้อมูลดังกล่าวภายใต้นโยบายความเป็นส่วนตัวของ Google และขอความยินยอมจากผู้ใช้ปลายทางที่เหมาะสมสำหรับการแชร์ดังกล่าวซึ่งเป็นไปตามข้อกำหนดทางกฎหมายที่เกี่ยวข้องทั้งหมด