Android oyunlarında arkadaşlar

Bu kılavuzda, Android Studio projelerinde Arkadaş API'lerinin nasıl kullanılacağı açıklanmaktadır.

Arkadaşları yükleme

Geçerli kullanıcıyla arkadaş olan oyuncuların listesini alıp oyunda görüntüleyebilirsiniz. Kullanıcılar, hangi oyunların arkadaş listesine erişebileceğini kontrol edebilir. Arkadaş listesini alırken izin gerektiren durumu ele almanız gerekir. Erişim isteğinde bulunmanın ve ardından arkadaş listesini kullanmanın basit bir işlem olmasını sağlamak için tüm bu işlemler API'ye yerleştirilmiştir. Arkadaş listesini yüklemek için aşağıdaki adımları uygulayın:

1. Task nesnesi döndüren eşzamansız bir çağrı olan PlayersClient.loadFriends() yöntemini çağırın.
2. Çağrı başarılı olursa (kullanıcı arkadaş listesine daha önce erişim izni verdiyse) Google Play Games Hizmetleri, kullanıcının arkadaşlarını temsil eden PlayerBuffer ile birlikte notlandırılmış bir liste döndürür.

3. Oyuncunun arkadaş listesine erişim izni vermesi gerekiyorsa çağrı FriendsResolutionRequiredException ile başarısız olur. Henüz herhangi bir iletişim kutusu gösterilmez.

   1. Bu istisna, oynatıcıdan izin isteyecek bir iletişim kutusunu tetikleyen bir Intent içerir. İzin iletişim kutusunu açmak için bu Intent'yi hemen başlatabilirsiniz. Bu Intent kodunu yalnızca bir kez kullanabilirsiniz.

   2. Intent etkinliğinin sonucu Activity.RESULT_OK ise izin verilmiştir. Arkadaş listesini döndürmek için loadFriends() numaralı telefonu tekrar arayın. Sonuç Activity.RESULT_CANCELLED ise kullanıcı izin vermemiştir ve loadFriends(), FriendsResolutionRequiredException değerini döndürmeye devam eder.

Aşağıdaki kodda, arkadaş listesinin nasıl yükleneceği gösterilmektedir:

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

Aşağıdaki kodda, izin isteğinden gelen sonucun nasıl ele alınacağı gösterilmektedir:

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

Başka bir oyuncunun profilini görüntüleme

Oyununuzdan başka bir oyuncunun Play Games profilini görüntüleyebilirsiniz. Bu görünüm, oyuncuların görüntülenen oyuncu için arkadaş davetleri göndermesine ve kabul etmesine olanak tanır. Bu görünüm için arkadaş listesine erişim gerekmez. Ayrıca, oyununuzda Play Games oyuncu kimliklerinden ayrı bir oyuncu adı kavramı varsa bu adları profil görünümüne iletebilirsiniz. Böylece, ek bağlam bilgisi için arkadaş davetlerine dahil edilebilirler.

Başka bir oyuncunun profilini göstermek için aşağıdaki adımları uygulayın:

1. Task nesnesi döndüren eşzamansız bir çağrı olan PlayersClient.getCompareProfileIntent() yöntemini çağırın.
2. Çağrı başarılı olursa Google Play Oyun Hizmetleri, kullanıcının kendisini başka bir oyuncunun profiliyle karşılaştırabileceği bir ekranın gösterileceği bir Intent döndürür.
3. Etkinlik başlatmak için önceki adımdaki Intent simgesini kullanın.

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

Oyunun oyuncular için kendi adı varsa bu adlar API çağrısına eklenebilir. Bu, Play Games'in oyununuzdan arkadaş daveti gönderen oyuncuların takma adını "<oyuna-özel-ad> from <oyun-adınız>" olarak ayarlamasını sağlar. Play Games, "from <oyun-adınız>" ifadesini otomatik olarak ekler):

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