Znajomi w grach na Androida

Z tego przewodnika dowiesz się, jak używać interfejsów API Friends w projektach Android Studio.

Wczytaj znajomych

Możesz pobrać i wyświetlić (w grze) listę graczy, którzy są znajomymi bieżącego użytkownika. Jako użytkownik możesz kontrolować, które gry mają dostęp do listy znajomych. Przy pobieraniu listy znajomych musisz przestrzegać zasad, które są wymagane. Wszystko to znajduje się w interfejsie API, dzięki czemu żądanie dostępu i korzystanie z listy znajomych jest prostym zadaniem. Aby wczytać listę znajomych, wykonaj następujące czynności:

1. Wywołaj metodę PlayersClient.loadFriends(), która jest asynchronicznym wywołaniem zwracającym obiekt Task.
2. Jeśli wywołanie się powiedzie (użytkownik przyznał już dostęp do listy znajomych), Usługi gier Google Play zwracają adnotację PlayerBuffer reprezentującą znajomych użytkownika.

3. Jeśli gracz musi przyznać dostęp do listy znajomych, wywołanie nie powiedzie się z powodu błędu FriendsResolutionRequiredException. Nie wyświetlają się jeszcze żadne okna.

   1. Ten wyjątek zawiera element Intent, który wywołuje okno z prośbą o zgodę na wykorzystanie danych. Możesz od razu uruchomić ten plik Intent, aby otworzyć okno z prośbą o zgodę na przetwarzanie danych osobowych. Intent możesz użyć tylko raz.

   2. Jeśli wynikiem działania funkcji Intent jest Activity.RESULT_OK, oznacza to, że użytkownik wyraził zgodę. Zadzwoń ponownie do użytkownika loadFriends(), aby zwrócić listę znajomych. Jeśli wynikiem jest Activity.RESULT_CANCELLED, użytkownik nie wyraził zgody, a loadFriends() nadal będzie 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 przetworzyć wynik prośby o zgodę na wykorzystanie danych:

/** 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 swojej grze możesz wyświetlić profil innego gracza w Grach Play. W tym widoku gracze mogą wysyłać i akceptować zaproszenia znajomych do oglądanego gracza. Ten widok nie wymaga dostępu do listy znajomych. Poza tym jeśli w Twojej grze są nazwy graczy niezależne od identyfikatorów gracza w Grach Play, możesz je przekazać do widoku profilu, aby można było uwzględnić ich w zaproszeniach do znajomych dla lepszego kontekstu.

Aby wyświetlić profil innego gracza, wykonaj te czynności:

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 gier Google Play zwracają intencję wyświetlającą ekran, na którym użytkownik może porównać się z profilem innego gracza.
3. Aby rozpocząć aktywność, użyj pola 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 Gry Play mogą ustawiać pseudonimy graczy, którzy wysyłają zaproszenia do znajomych z poziomu gry na „<nazwa-konkretnej-gry> w Grach Play>”. W Grach Play automatycznie dodajemy ciąg „z <nazwa-Twojej-gry>”):

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