Tích hợp Recall API của Dịch vụ trò chơi của Play trong trò chơi

Trang này giải thích cách triển khai Recall API trong trò chơi của bạn. Trước tiên, bạn sẽ được hướng dẫn cách thiết lập máy chủ và ứng dụng khách của trò chơi để hỗ trợ API này, sau đó là về cách lưu trữ và truy xuất mã thông báo (token).

Thiết lập máy chủ trò chơi

Thiết lập máy chủ trò chơi để thực hiện lệnh gọi Recall API đến máy chủ của Google.

1. Thiết lập dự án Dịch vụ trò chơi của Play (PGS)

(Nếu chưa hoàn tất) Làm theo hướng dẫn trong bài viết Thiết lập Dịch vụ trò chơi của Google Play.

Lưu ý: Mã gọi lại và persona được cung cấp dựa trên từng dự án PGS. Tức là mã thông báo và persona được lưu trữ theo từng dự án PGS. Ngoài ra, đối với các dự án PGS riêng biệt, hồ sơ PGS và persona sẽ có những tập hợp đường liên kết riêng. Bạn nên tham khảo tài liệu này khi xác định cách thiết lập dự án PGS.

2. Thiết lập tài khoản dịch vụ cho trò chơi

Làm theo hướng dẫn về cách tạo tài khoản dịch vụ. Sau khi hoàn tất hướng dẫn, bạn sẽ có một tệp JSON chứa thông tin đăng nhập tài khoản dịch vụ.

Lưu ý: Recall API là một API từ máy chủ đến máy chủ thuần tuý. Do đó, Recall API sử dụng tài khoản dịch vụ để xác thực máy chủ trò chơi, chứ không phải OAuth 3 bên thông thường được API Games khác sử dụng để xác thực cả máy chủ trò chơi lẫn người dùng cuối.

3. Tải thư viện Java phía máy chủ xuống cho PlayGamesServices

Tải thư viện google-api-services-games mới nhất xuống rồi tải lên máy chủ của bạn.

4. Chuẩn bị thông tin đăng nhập cho các lệnh gọi Recall API

Xem bài viết Chuẩn bị thực hiện lệnh gọi API được uỷ quyền để biết thêm thông tin.

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

Thiết lập ứng dụng trò chơi

Thiết lập ứng dụng trò chơi để truy xuất ID phiên hoạt động gọi lại mà máy chủ của bạn sử dụng để giao tiếp với các máy chủ của Google.

SDK Java

Thiết lập SDK Java trong ứng dụng khách và đừng quên đưa com.google.android.gms:play-services-games-v2:19.0.0 và com.google.android.gms:play-services-tasks:18.0.2 trở lên vào tệp Gradle.

Để giao tiếp với máy chủ của Google với thông tin chính xác, bạn cần yêu cầu ID phiên hoạt động gọi lại từ SDK ứng dụng khách mà bạn gửi đến máy chủ trò chơi.

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

SDK Unity

Nếu chưa hoàn tất, hãy thiết lập SDK Unity trong ứng dụng khách.

Để giao tiếp với máy chủ của Google với thông tin chính xác, bạn cần yêu cầu ID phiên hoạt động gọi lại từ SDK ứng dụng khách rồi gửi ID này đến máy chủ trò chơi.

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

Sử dụng Recall API trong máy chủ trò chơi

Sau khi định cấu hình máy chủ và ứng dụng khách, bạn có thể gửi recallSessionID từ ứng dụng trò chơi đến máy chủ trò chơi rồi làm theo hướng dẫn bên dưới để bắt đầu sử dụng API Java để lưu trữ, truy xuất hoặc xoá Mã gọi lại phía máy chủ.

Lưu trữ mã

Bạn có thể lưu trữ persona và mã thông báo trò chơi của người dùng bằng cách sử dụng đối tượng LinkPersonaRequest. Bạn cần sử dụng GoogleCredential để gọi API của Google (Xem bài viết Gọi API của Google để biết thêm thông tin). Lưu ý rằng, theo Giới hạn về số lượng giá trị riêng biệt 1:1, bạn chỉ có thể liên kết một persona với một hồ sơ PGS (và ngược lại). Bạn nên thiết lập Chính sách xử lý xung đột trong trường hợp hồ sơ PGS này đã được liên kết với một persona khác.

Nếu muốn, bạn có thể chọn thiết lập TTL trên mã thông báo. Thao tác này sẽ khai báo khoảng thời gian mã thông báo có hiệu lực bằng cách sử dụng đối tượng Durations (Thời lượng). Bạn có thể chọn thiết lập giá trị này bằng cách sử dụng SetTtl() (như trình bày bên dưới) để thiết lập ngày hết hạn từ khoảng thời gian được chỉ định trong phương thức, hoặc setExpireTime() để đặt giá trị chính xác cho thời điểm mã thông báo hết hạn.

Bạn phải mã hoá persona và mã thông báo của trò chơi và không đưa vào bất kỳ thông tin nhận dạng cá nhân nào. Chuỗi mã thông báo và persona có thể dài tối đa 256 ký tự và trong mỗi trò chơi, nhà phát triển có thể lưu trữ tối đa 20 mã thông báo hoặc persona cho mỗi người chơi.

Tại một thời điểm, chỉ có thể lưu một mã thông báo cho mỗi persona của một người chơi. Việc cố gắng lưu trữ một mã thông báo khác cho cùng persona sẽ ghi đè mã thông báo ban đầu.

Lưu ý: Khoá mã hoá dùng để mã hoá mã thông báo phải là duy nhất cho từng ứng dụng. Nếu trò chơi được chuyển cho một nhà phát triển khác, thì khoá mã hoá phải được chuyển cho chủ sở hữu mới. Không thể giải mã mã gọi lại nếu không có khoá mã hoá ban đầu.

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
}

Truy xuất mã

Có 3 cách để truy xuất mã thông báo tuỳ theo nhu cầu của trò chơi. Bạn có thể yêu cầu những nội dung sau:

• Các mã thông báo được liên kết với trò chơi hiện tại, bao gồm cả mã gọi lại trong phạm vi trò chơi.
• Mã thông báo gần đây nhất được lưu trữ trên tất cả trò chơi do tài khoản nhà phát triển sở hữu.
• Cung cấp danh sách trò chơi do tài khoản nhà phát triển sở hữu, tất cả mã gọi lại liên kết với từng trò chơi.

Lưu ý: Khi bạn yêu cầu mã gọi lại, API sẽ không trả về chuỗi đại diện cho persona.

Mã gọi lại trong phạm vi trò chơi

Để truy xuất mã gọi lại của trò chơi hiện tại, hãy lấy recallSessionId từ ứng dụng và truyền mã đó vào 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
}

Mã gọi lại mới nhất trên tất cả trò chơi do tài khoản nhà phát triển sở hữu

Để truy xuất mã thông báo mới nhất được lưu trữ trên tất cả trò chơi do tài khoản nhà phát triển sở hữu trong Google Play Console, bạn cần lấy recallSessionId từ ứng dụng và truyền mã đó vào API lastTokenFromAllDeveloperGames, như minh hoạ trong đoạn mã sau đây. Trong phản hồi, bạn có thể kiểm tra Mã ứng dụng được liên kết với mã thông báo này.

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.
}

Tất cả mã gọi lại trong một danh sách trò chơi nhất định do tài khoản nhà phát triển sở hữu

Để truy xuất tất cả mã thông báo liên kết với danh sách trò chơi do tài khoản nhà phát triển của bạn sở hữu trong Google Play Console, hãy lấy recallSessionId từ ứng dụng và truyền mã đó vào API gamesPlayerTokens. Cung cấp danh sách Mã nhận dạng ứng dụng.

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.
}

Xoá mã gọi lại

Nếu cần, bạn cũng có thể xoá mã gọi lại bằng lệnh gọi sau:

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

Bật chế độ không có hồ sơ

Bạn có thể bật chức năng Recall API giới hạn cho người dùng không có hồ sơ PGS bằng cách làm theo các bước sau:

1. Bật tính năng gọi lại không cần hồ sơ cho dự án trò chơi PGS trong Play Console.
2. Vui lòng xem các điều khoản bổ sung được mô tả ở phần sau của phần này.
3. Thêm thẻ siêu dữ liệu sau vào tệp kê khai ứng dụng:

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

Điều khoản bổ sung

Ngoài việc phải tuân thủ Điều khoản dịch vụ của Dịch vụ trò chơi của Play, bạn đồng ý rằng nếu bạn sử dụng Recall API cho người dùng không có hồ sơ PGS, cho phép chia sẻ dữ liệu của người dùng cuối với Google mà không cần họ có hồ sơ Dịch vụ trò chơi của Play, thì trước khi chia sẻ dữ liệu đó với Google, bạn phải cung cấp cho người dùng cuối thông báo thích hợp.