Lider tahtaları

Oyun sayfasında kişiselleştirilmiş lider tahtalarını (lider tabloları) en iyi oyuncuların sonuçlarıyla ve giriş yapmış kullanıcının sıralamadaki konumuyla gösterebilirsiniz.

Lider tahtalarına yapılan isteklerin çalışması için şu koşulları yerine getirin:

Oyun kodunda SDK'yı bağlayın ve yapılandırın, böylece nesnesi ysdk değişkeni aracılığıyla erişilebilir olsun;
Geliştirici Konsolunda lider tahtasını oluşturun.

Dikkat

Konsol'da Technical leaderboard name alanında ilgili ada sahip bir lider tahtası yoksa, istekler 404 hatası verecektir.

Başlatma

Lider tahtası metodlarını çağırmak için doğrudan ysdk.leaderboards'a başvurun.

Dikkat

ysdk.getLeaderboards() metoduyla lb nesnesinin başlatılması artık kullanımdan kaldırılmıştır.

Eski metodlar

1const ysdk = await YaGames.init();
2
3const lb = await ysdk.getLeaderboards();
4
5// Lider tahtası metodlarının eski ve yeni yöntemlerle çağrılmasının karşılığı:
6// lb.getLeaderboardDescription() → ysdk.leaderboards.getDescription()
7// lb.setLeaderboardScore() → ysdk.leaderboards.setScore()
8// lb.getLeaderboardPlayerEntry() → ysdk.leaderboards.getPlayerEntry()
9// lb.getLeaderboardEntries() → ysdk.leaderboards.getEntries()

Lider tahtası açıklaması

Lider tahtasının açıklamasını adına göre almak için ysdk.leaderboards.getDescription() metodunu kullanın.

Metodun imzası:

 1interface ILeaderboardDescription {
 2    appID: string;
 3    default: boolean;
 4    description: {
 5        invert_sort_order: boolean;
 6        score_format: {
 7            options: {
 8                decimal_offset: number;
 9            };
10            type: 'numeric' | 'time';
11        };
12        sort_order: string;
13    };
14    name: string;
15    title: Record<Locale, string>;
16}
17
18function getDescription(
19    leaderboardName: string
20): Promise<ILeaderboardDescription> {}

Tek parametre olarak lider tahtasının teknik adını leaderboardName alır. Aşağıdaki alanları içeren lider tahtası açıklamasıyla bir nesne döndürür:

Parametre	Tür	Açıklama
`appID`	`string`	Uygulama kimliği.
`default`	`boolean`	`true` ise, lider tablosu ana lider tablosudur.
`invert_sort_order`	`boolean`	Sıralama yönü: `false` — azalan sırada (en yüksek puana sahip kullanıcılar ilk sıralarda yer alır). `true` — artan sırada (en düşük puana sahip kullanıcılar ilk sıralarda yer alır).
`sort_order`	`string`	Dize formatında sıralama yönü: `'DESC'` — azalan sırada. `'ASC'` — artan sırada.
`decimal_offset`	`number`	Puanın ondalık kısmının boyutu. Örneğin, `decimal_offset: 2` ile 1234 sayısı 12.34 olarak görüntülenir.
`type`	`'numeric'` \| `'time'`	Lider tablosu sonuç türü. Mevcut değerler: `numeric` (sayı), `time` (milisaniye).
`name`	`string`	Konsolda Technical leaderboard name alanında belirtilen lider tablosu adı.
`title`	`Record<Locale, string>`	Yerelleştirilmiş başlıkların listesi. Olası dil kodları Diller ve alan adları sayfasında listelenmiştir.

Örnek

1const ysdk = await YaGames.init();
2
3const lb = await ysdk.leaderboards.getDescription('leaderboard2021');
4
5console.log(lb);

Yeni sonuç

Dikkat

İstek yalnızca giriş yapmış kullanıcılar için kullanılabilir. Giriş durumunu nasıl kontrol edeceğinizi ve giriş diyalogunu nasıl çağıracağınızı Kullanıcı yetkilendirmesi bölümünde bulabilirsiniz.

İsteği göndermeden önce ysdk.isAvailableMethod('leaderboards.setScore') ile metodun kullanılabilirliğini kontrol edin. Metod Promise<Boolean> döndürür.

Sonuçların girişten bağımsız olarak tüm kullanıcılar için kaydedilmesini sağlamak için, uygulama kodunda özel bir lider tahtasını kendiniz yazmanızı öneririz. Teknoloji seçimi sınırlı değildir.

Oyuncuya yeni bir sonuç ayarlamak için ysdk.leaderboards.setScore() metodunu kullanın.

Metodun imzası:

1function setScore(
2    leaderboardName: string,
3    score: number,
4    extraData?: string
5): Promise<void> {}

Üç parametre alır:

Parametre	Tür	Açıklama
`leaderboardName`	`string`	Konsolda Technical leaderboard name alanında belirtilen lider tablosu adı.
`score`	`number`	Sonuç değeri. Negatif olamaz, maksimum değer yalnızca JavaScript mantığıyla sınırlıdır. Lider tablosu türü `time` ise, değer milisaniye cinsinden iletilmelidir.
`extraData`	`string`	Kullanıcı açıklaması. İsteğe bağlı parametre.

Not

İstek 1 saniyede en fazla 1 kez gönderilebilir, aksi takdirde hatayla reddedilecektir.

Örnek

1const ysdk = await YaGames.init();
2
3await ysdk.leaderboards.setScore('leaderboard2021', 120);
4
5await ysdk.leaderboards.setScore('leaderboard2021', 120, 'My favourite player!');

Sıralama alınması

Dikkat

İsteği göndermeden önce ysdk.isAvailableMethod('leaderboards.getPlayerEntry') ile metodun kullanılabilirliğini kontrol edin. Metod Promise<Boolean> döndürür.

Kullanıcının sıralamasını almak için ysdk.leaderboards.getPlayerEntry() metodunu kullanın.

Metodun imzası:

 1interface ILeaderboardEntry {
 2    extraData: string;
 3    rank: number;
 4    score: number;
 5    player: {
 6        publicName: string;
 7        uniqueID: string;
 8        getAvatarSrc: (size?: 'small' | 'medium' | 'large') => string;
 9        getAvatarSrcSet: (size?: 'small' | 'medium' | 'large') => string;
10    }
11}
12
13function getPlayerEntry(
14    leaderboardName: string
15): Promise<ILeaderboardEntry> {}

Tek parametre olarak lider tahtasının teknik adını leaderboardName alır. Aşağıdaki alanları içeren kullanıcı sıralamasıyla bir nesne döndürür:

Parametre	Tür	Açıklama
`score`	`number`	Sonuç değeri.
`rank`	`number`	Kullanıcının lider tablosundaki konumu.
`extraData`	`string`	Kullanıcı açıklaması.
`publicName`	`string`	Kullanıcı adı.
`uniqueID`	`string`	Kullanıcının benzersiz kimliği.
`getAvatarSrc`	`(size?: TSize) => string`	Belirtilen boyutta kullanıcı avatarının URL'sini döndürür. Olası `size` değerleri: `small`, `medium`, `large`.
`getAvatarSrcSet`	`(size?: TSize) => string`	Retina ekranlar için uygun kullanıcı avatarının srcset'ini döndürür. Olası `size` değerleri: `small`, `medium`, `large`.

Not

İstek 5 dakikada en fazla 60 kez gönderilebilir, aksi takdirde hatayla reddedilecektir.

Örnek

 1const ysdk = await YaGames.init();
 2
 3try {
 4    const res = await ysdk.leaderboards.getPlayerEntry('leaderboard2021');
 5
 6    console.log(res);
 7} catch (err) {
 8    if (err.code === 'LEADERBOARD_PLAYER_NOT_PRESENT') {
 9        // Oyuncunun lider tahtasında kaydı yoksa tetiklenir.
10    }
11}

Lider tahtası kayıtları

Kullanıcı sıralamasını görüntülemek için ysdk.leaderboards.getEntries() metodunu kullanın.

Metodun imzası:

 1interface ILeaderboardEntries {
 2    leaderboard: ILeaderboardDescription;
 3    ranges: {
 4        start: number;
 5        size: number;
 6    }[];
 7    userRank: number;
 8    entries: ILeaderboardEntry[];
 9}
10
11function getEntries(
12    leaderboardName: string,
13    options: {
14        includeUser?: boolean;
15        quantityAround?: number;
16        quantityTop?: number;
17    }
18): Promise<ILeaderboardEntries> {}

Lider tahtasının teknik adını leaderboardName ve isteğe bağlı options parametrelerini alır:

Seçenek	Tür	Açıklama
`includeUser`	`boolean`	Yetkilendirilmiş kullanıcının yanıta dahil edilip edilmeyeceğini belirler: `true` — yanıta dahil edilir. `false` (varsayılan) — dahil edilmez.
`quantityAround`	`number`	Lider tablosunda kullanıcının altında ve üstünde döndürülecek kayıt sayısı. Minimum değer 1, maksimum değer 10. Varsayılan olarak 5 döndürülür.
`quantityTop`	`number`	Lider tablosu zirvesinden kayıt sayısı. Minimum değer 1, maksimum değer 20. Varsayılan olarak 5 döndürülür.

Aşağıdaki alanları içeren kullanıcı sıralamasıyla Promise<ILeaderboardEntries> nesnesi döndürür:

Parametre	Tür	Açıklama
`leaderboard`	`ILeaderboardDescription`	Lider tahtası açıklaması
`ranges`	`object[]`	Yanıttaki konum aralıkları.
`start`	`number`	Sıralamadaki konum. Sayım sıfırdan başlar, bu nedenle 1. konum sıfırıncı öğe olarak kabul edilir.
`size`	`number`	İstenen kayıt sayısı. Yeterli veri yoksa, yanıtla eşleşmeyebilir.
`userRank`	`number`	Kullanıcının sıralamadaki konumu. Yoksa veya kullanıcı dahil edilmeden zirve isteği yapılmışsa 0'a eşittir.
`entries`	`ILeaderboardEntry[]`	Sıralama kayıtları dizisi. Kayıt, Sıralama alınması metodundan döndürülen değerle aynıdır.

Not

İstek 5 dakikada en fazla 20 kez gönderilebilir, aksi takdirde hatayla reddedilecektir.

Örnek

 1const ysdk = await YaGames.init();
 2
 3// En iyi 10 oyuncuyu ve kullanıcının yakınındaki 3 kaydı alma.
 4const entries = await ysdk.leaderboards.getEntries('leaderboard2021', {
 5    quantityTop: 10,
 6    includeUser: true,
 7    quantityAround: 3
 8});
 9
10console.log(entries);

Metod kısıtlamaları

Metod	Açıklama	Limit	Kullanıcı yetkilendirmesi
`ysdk.leaderboards.setScore()`	Oyuncunun yeni sonucunu ayarla	1 saniyede 1 istek	Zorunlu
`ysdk.leaderboards.getPlayerEntry()`	Tek bir kullanıcının sıralamasını görüntüle	5 dakikada 60 istek	Zorunlu
`ysdk.leaderboards.getEntries()`	Birden fazla kullanıcının sıralamasını al	5 dakikada 20 istek	İsteğe bağlı

Diğer istekler için limit: 5 dakikada 20 istek.

Sorun çözme

Öneri

ysdk.isAvailableMethod() ve ysdk.leaderboards.setScore() metodlarının kombinasyonunu kullanırken, giriş yapmamış kullanıcılar lider tahtasına dahil olmaz ve ilerlemelerini göremezler. Sonuçların tüm oyuncular için kaydedilmesini sağlamak için, uygulama kodunda özel bir lider tahtası oluşturmanızı öneririz. Teknoloji seçimi sınırlı değildir.

Object already exists

Hata, eski bir adla yeni bir lider tahtası oluşturulmaya çalışıldığında ortaya çıkar. Daha önce kullanılmamış bir ad girin.

Kullanıcı gizli

"Kullanıcı gizli" yazısı, oyuncu avatarını ve adını kullanma izni vermediğinde görüntülenir. Kullanıcı verilerine erişim, profilindeki ayarlara bağlıdır. Daha fazla bilgi için Başlatma bölümüne bakın.

Hata 404

Lider tahtası için SDK metodlarını çağırırken 404 hatası oluşuyorsa, Geliştirici Konsolu'nda Technical leaderboard name alanında ilgili ada sahip bir lider tahtasının oluşturulduğunu kontrol edin.

Not

Destek ekibi, hazır oyunu Yandex Oyun platformuna yerleştirmenize yardımcı olur. Geliştirme ve test etme konularındaki uygulamalı sorulara ise diğer geliştiriciler Discord Topluluğu yanıt verir.

Yandex Games SDK kullanırken sorunla karşılaşırsanız veya sorunuz varsa, lütfen destek ekibiyle iletişime geçin:

Sohbete yaz

Yazı yararlı oldu mu?

Uygulama içi satın alımlar

Asenkron çok oyunculu