Znajomi w grach na Androida

Ten przewodnik wyjaśnia, jak używać interfejsów API Friends w projektach w Android Studio.

Ładowanie znajomych

Możesz pobrać i wyświetlić (w grze) listę graczy, którzy są znajomymi obecnego użytkownika. Użytkownik może kontrolować, które gry mają dostęp do listy znajomych. Podczas pobierania listy znajomych musisz obsłużyć przypadek, w którym wymagane jest pozwolenie. Wszystko to jest zaszyte w interfejsie API, aby żądanie dostępu i następnie korzystanie z listy znajomych było proste. Aby załadować listę znajomych:

  1. Wywołaj metodę PlayersClient.loadFriends(), która jest asynchronicznym wywołaniem zwracającym obiekt Task.
  2. Jeśli wywołanie zakończy się powodzeniem (użytkownik już przyznał dostęp do listy znajomych), usługi Google Play Games zwraca adnotowaną PlayerBuffer, która reprezentuje listę znajomych użytkownika.

  3. Jeśli gracz musi przyznać dostęp do listy znajomych, wywołanie zakończy się niepowodzeniem z komunikatem FriendsResolutionRequiredException. Nie wyświetlają się jeszcze żadne dialogi.

    1. To wyjątek zawierający Intent, który uruchamia okno z prośbą o zgodę na odtwarzanie. Możesz od razu uruchomić tę Intent, aby otworzyć okno zgody. Z tej Intent możesz skorzystać tylko raz.

    2. Jeśli wynik działania Intent to Activity.RESULT_OK, oznacza to, że użytkownik wyraził zgodę. Aby powrócić do listy znajomych, ponownie wybierz loadFriends(). Jeśli wynik to Activity.RESULT_CANCELLED, użytkownik nie wyraził zgody, a wartość loadFriends() będzie nadal zwracać wartość FriendsResolutionRequiredException.

Poniższy kod pokazuje, jak wczytać listę znajomych:

// Attempt loading friends.
// Register a success listener to handle the successfully loaded friends list.
// Register a failure listener to handle asking for permission to access the list.
PlayGames.getPlayersClient(this)
    .loadFriends(PAGE_SIZE, /* forceReload= */ false)
    .addOnSuccessListener(
        new OnSuccessListener<AnnotatedData<PlayerBuffer>>() {
            @Override
            public void onSuccess(AnnotatedData<PlayerBuffer>  data) {
          PlayerBuffer playerBuffer = data.get();
          // ...
        })

    .addOnFailureListener(
        exception -> {
      if (exception instanceof FriendsResolutionRequiredException) {
        PendingIntent pendingIntent =
            ((FriendsResolutionRequiredException) task.getException())
            .getResolution();
        parentActivity.startIntentSenderForResult(
            pendingIntent.getIntentSender(),
            /* requestCode */ SHOW_SHARING_FRIENDS_CONSENT,
            /* fillInIntent */ null,
            /* flagsMask */ 0,
            /* flagsValues */ 0,
            /* extraFlags */ 0,
            /* options */ null);
     }
   });
 return;
}

Ten kod pokazuje, jak obsłużyć wynik żądania zgody:

/** Handle the activity result from the request for consent. */
@Override
public void onActivityResult(int requestCode, int result, Intent data) {
  if (requestCode == SHOW_SHARING_FRIENDS_CONSENT) {
    if (result == Activity.RESULT_OK) {
      // We got consent from the user to access their friends. Retry loading the friends
      callLoadFriends();
    } else {
      // User did not grant consent.
    }
  }
}

Wyświetlanie profilu innego gracza

W grze możesz wyświetlić profil innego gracza w Grach Play. Ten widok umożliwia graczom wysyłanie i akceptowanie zaproszeń do znajomych w przypadku wyświetlanego gracza. Ten widok nie wymaga dostępu do listy znajomych. Jeśli w Twojej grze występuje osobna koncepcja nazw graczy niż identyfikatory graczy w Grach Play, możesz przekazać te nazwy do widoku profilu, aby można było uwzględnić je w zaproszeniu do dodania znajomego jako dodatkowy kontekst.

Aby wyświetlić profil innego gracza:

  1. Wywołaj metodę PlayersClient.getCompareProfileIntent(), która jest asynchronicznym wywołaniem zwracającym obiekt Task.
  2. Jeśli wywołanie się powiedzie, usługi Gry Google Play zwrócą intencję, która wyświetli ekran, na którym użytkownik może porównać swój profil z profilem innego gracza.
  3. Aby rozpocząć aktywność, użyj Intent z poprzedniego kroku.
// Retrieve and launch an Intent to show a player profile within the game.
PlayGames.getPlayersClient(this)
    .getCompareProfileIntent(otherPlayerId)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});

Jeśli gra ma własną nazwę dla graczy, można ją dodać do wywołania interfejsu API. Dzięki temu możesz ustawić pseudonimy graczy, którzy wysyłają zaproszenia do grona znajomych z Twojej gry, na „<game-specific-name> z <your-game-name>”. Play Games automatycznie doda „z <your-game-name>”:

// Show a player profile within the game, with additional hints containing the
// game-specific names for both players.
// - otherPlayerId is the Play Games playerId of the player to view.
// - otherPlayerInGameName is the game-specific name of the player being viewed.
// - currentPlayerInGameName is the game-specific name of the player who is signed
//   in. Hence if the player sends an invitation to the profile they are viewing,
//   their game-specific name can be included.
PlayGames.PlayersClient(this)
    .getCompareProfileIntentWithAlternativeNameHints(otherPlayerId, otherPlayerInGameName, currentPlayerInGameName)
    .addOnSuccessListener(new OnSuccessListener<Intent>() {
        @Override
        public void onSuccess(Intent  intent) {
          startActivityForResult(intent, RC_SHOW_PROFILE);
          // ...
        }});