Obiettivi e Classifiche

Classifiche

Creazione di una Classifica

Questa sezione spiega come creare una classifica per un gioco nuovo o esistente. Il limite massimo è di 20 classifiche, e ogni ID classifica deve essere univoco all'interno del gioco.

Per creare una classifica, accedi alla pagina di gestione GameRank corrispondente al tuo gioco, seleziona Estensioni > Add e clicca sul pulsante Crea Classifica.

Successivamente, compila le informazioni richieste per la classifica.

Formato Punteggio

• Classifiche Numeriche mostrano il punteggio in formato numerico. Possono essere interi o numeri decimali, ad esempio 3.14159, 3141.59 o 314159.
  Attenzione: non utilizzare valori troppo grandi; al momento è supportata solo la precisione singola.

• Classifiche Temporali mostrano il punteggio nel formato ore / minuti / secondi / centesimi di secondo o nel formato orologio tradizionale (HH:MM:SS), ad esempio 66032, 1:06:3.

• Punteggi Formattati vengono mostrati in un formato personalizzato. Invia il punteggio nel formato valuta, ad esempio $19.95.

Linee Guida Immagine di Sfondo

L'immagine di sfondo della classifica deve essere un file JPEG 1024 × 1024.
È facoltativa; se non caricata, verrà usata l'immagine predefinita della piattaforma.
La stessa immagine viene utilizzata per tutte le lingue, quindi si consiglia di evitare testi o contenuti localizzati.

Gestione Classifiche

Per l'elenco delle classifiche, gli sviluppatori possono gestire giocatori anomali come segue:

• Elimina: rimuove i dati attualmente mostrati del giocatore dalla classifica.
• Aggiungi alla Lista Nera: impedisce al giocatore di partecipare a tutte le classifiche di questo gioco in futuro.
  Dopo l'aggiunta, è possibile visualizzare e rimuovere i giocatori dalla lista nera in tutte le classifiche.
• Modifica Dati: clicca per aprire la pagina di modifica della classifica.
• Elimina Classifica: clicca per eliminare la classifica selezionata.

Campi di Invio Dati Classifica

Quando i dati di un giocatore rientrano in una classifica definita, chiama l'API di invio dati per inviare i dati corrispondenti al backend Jogos.
Il giocatore potrà quindi aprire la finestra classifiche sulla piattaforma Jogos per visualizzare la classifica e la propria posizione.

Nota: il nome della classifica e il tipo di dati nei parametri dell'API devono corrispondere a quelli definiti nel Developer Center.

Nel Developer Center è possibile creare tre tipi di dati da inviare:

• Punteggio Numerico: number
• Punteggio Temporale: time
• Punteggio Formattato: personalizzato

I dati inviati devono essere coppie chiave-valore. I valori possono essere solo number, string o date, e devono corrispondere al formato configurato nel Developer Center.

API Invio Dati Classifica

API: JOGOS_SDK.game.commitRankingData

== HTML5

/**
 * Invia dati classifica
 *
 * @param rankingName ID classifica
 * @param data Dati classifica
 */
await window.JOGOS_SDK.game.commitRankingData(rankingName: string, data: { [key: string]: any });

== Cocos

/**
 * Invia dati classifica
 *
 * @param rankingName ID classifica
 * @param data Dati classifica
 */
await JOGOS_SDK.game.commitRankingData(rankingName: string, data: { [key: string]: any });

== Unity

API: JogosSDK.Game.CommitRankingData

/// <summary>
/// Invia dati classifica
/// </summary>
/// <param name="rankingName"></param> ID classifica
/// <param name="rankingData"></param> Dati da inviare
/// <param name="action"></param> Callback di successo
public void CommitRankingData(string rankingName, string rankingData, Action<bool> action)

// Esempio:
JsonObject json = new JsonObject();
json["number"] = 1;
JogosSDK.Game.CommitRankingData("LevelRank", json.ToString(), (isSucc) =>
{
    Debug.Log("CommitRankingData isSucc:" + isSucc);
});

:::

API Apertura Interfaccia Classifica

API: JOGOS_SDK.game.openRankingDialog
Per mostrare una specifica classifica (invece di tutte), passa il nome della classifica (identico a quello creato nel Developer Center) a questo metodo.

== HTML5

/**
 * Apri finestra classifica
 *
 * @param rankingName Nome classifica
 */
await window.JOGOS_SDK.game.openRankingDialog(rankingName: string);

== Cocos

/**
 * Apri finestra classifica
 *
 * @param rankingName Nome classifica
 */
await JOGOS_SDK.game.openRankingDialog(rankingName: string);

== Unity

/// <summary>
/// Apri interfaccia classifica
/// </summary>
/// <param name="rankingName"></param> Nome classifica
/// <param name="action"></param> Callback apertura interfaccia
public void OpenRankingDialog(string rankingName, Action<bool> action)

// Esempio:
JogosSDK.Game.OpenRankingDialog("LevelRank", (isSucc) =>
{
    Debug.Log("OpenRankingDialog isSucc:" + isSucc);
});

:::

Integrazione Obiettivi

Quando un giocatore sblocca un obiettivo, chiama l'API di invio dati per inviare i dati corrispondenti al backend Jogos.
Il giocatore potrà quindi aprire la finestra obiettivi sulla piattaforma Jogos per visualizzare gli obiettivi sbloccati.

Nota: il nome dell'obiettivo nei parametri dell'API deve corrispondere a quello definito nel Developer Center.

Per obiettivi non a step:

• Invia solo quando l'obiettivo è sbloccato. Non c'è progresso visibile—l'invio indica il completamento.

Per obiettivi a step:

• Invia il progresso corrispondente all'ID dello step. Ad esempio, quando lo step 2 è completato, invia progress = 2.

Creazione di un Obiettivo

Nel Developer Center, apri GameService > Obiettivi e seleziona Crea Obiettivo.
Compila il modulo nella pagina Aggiungi Obiettivo.

Ogni obiettivo include i seguenti elementi fondamentali:

• ID Obiettivo: stringa alfanumerica, univoca per gioco, usata per abbinare report in-game e visualizzazione.
• Nome: nome visualizzato dell'obiettivo (es. "Pieman").
• Condizione Obiettivo: descrizione che spiega al giocatore come sbloccare l'obiettivo.
• Icona: icona quadrata per l'obiettivo. Carica sia la versione bloccata che sbloccata.
• Tipi di Obiettivo (scelta singola, mostrati separatamente nell'UI):
  • Obiettivi Esplorazione Principiante – fino a 900.
  • Obiettivi Sfida Intermedia – fino a 50.
  • Obiettivi Gloria Avanzata – fino a 10.

Stati

• Obiettivo Nascosto: i dettagli sono nascosti. Jogos fornisce descrizione e icona generica.
  Usa questo per spoiler (es. "Scopri che eri un fantasma fin dall'inizio!").

• Obiettivo Rivelato: il giocatore conosce l'obiettivo ma non l'ha ancora sbloccato.
  La maggior parte degli obiettivi inizia in questo stato.

• Obiettivo Sbloccato: il giocatore ha completato l'obiettivo.
  Gli obiettivi possono essere sbloccati offline; il gioco si sincronizza con Jogos quando online.

Obiettivi a Step

• Gli obiettivi possono essere standard o a step.
  Gli obiettivi a step richiedono progressi nel tempo. Invia lo step corrente del giocatore a Jogos, che tiene traccia del progresso e informa il gioco (e il giocatore) quando l'obiettivo è completato.

Linee Guida Icona

Le icone devono essere file PNG, JPEG o JPG 512 × 512.
Fornisci solo l'icona sbloccata; si consiglia di usare colori per distinguere gli obiettivi sbloccati.
Usa la stessa icona per tutte le lingue—evita testi o contenuti localizzati.

API Invio Obiettivi

== HTML5

/**
 * Invia dati obiettivo giocatore
 *
 * @param name ID obiettivo
 * @param progress Progresso completamento
 * @param hidden Flag nascosto
 */
await window.JOGOS_SDK.game.commitAchievementsData(name: string, progress: number, hidden: boolean);

== Cocos

/**
 * Invia dati obiettivo giocatore
 *
 * @param name ID obiettivo
 * @param progress Progresso completamento
 * @param hidden Flag nascosto
 */
await JOGOS_SDK.game.commitAchievementsData(name: string, progress: number, hidden: boolean);

== Unity

/// <summary>
/// Invia dati obiettivo
/// </summary>
/// <param name="name"></param> ID obiettivo
/// <param name="progress"></param> Progresso
/// <param name="hidden"></param> Flag nascosto
/// <param name="action"></param> Callback di successo
public void CommitAchievementData(string name, int progress, bool hidden, Action<bool> action)

// Esempio:
JogosSDK.Game.CommitAchievementData("level", 1, false, (isSucc) =>
{
    Debug.Log("CommitAchievementData level,isSucc:" + isSucc);
});

Per obiettivi a step:

Invia ogni step:

JogosSDK.Game.CommitAchievementData("Event", 1, false, null);

Se devi anche inviare il progresso totale:

• progress: se l'obiettivo a step ha 3 step e 2 sono completati, invia 2 (l'ordine non conta).

JogosSDK.Game.CommitAchievementData("Root", 2, false, null);

:::

API Apertura Interfaccia Obiettivi

Jogos fornisce una finestra integrata degli obiettivi del giocatore. Puoi aprirla dal tuo gioco.

== HTML5

// Apri finestra obiettivi giocatore
await window.JOGOS_SDK.game.openAchievementsDialog();

== Cocos

// Apri finestra obiettivi giocatore
await JOGOS_SDK.game.openAchievementsDialog();

== Unity

API: JogosSDK.Game.OpenAchievementsDialog

/// <summary>
/// Apri interfaccia obiettivi
/// </summary>
/// <param name="action">Callback apertura interfaccia</param>
public void OpenAchievementsDialog(Action<bool> action)

// Esempio:
JogosSDK.Game.OpenAchievementsDialog((isSucc) =>
{
    Debug.Log("OpenAchievementsDialog isSucc:" + isSucc);
});

:::