Skip to main content

Implement Progression

One of the appealing aspects of the most popular mobile games is the concept of progression. That is, your investment in the gameplay over time yields additional benefits and rewards. This provides a sense of accomplishment players, as well as giving them goals to shoot for, helping to ensure they have a reason to keep coming back again and again.

Progression provides a way for developers to add this critical component, to help drive the success of their games. The Progression methods allow developers to store, recall, and update player data at any time within the game, unlocking personalized player experiences. For a broader overview of Progression features, see Progression and Player Data

General Custom Progression Game Scene Flow​

  1. Create keys in Developer Console for PlayerData and/or InGameItems namespaces
  2. From client, retrieve player data using GetProgressionUserData at any time, prior, during, or at end of match play
  3. Call SubmitScore at the conclusion of the match
  4. Call UpdateProgressionUserData to update player data
  5. Present the player with the custom progression scene
  6. Call ReturnToSkillz to return to the Skillz UI

Progression API​

Namespaces​

There are three namespaces used to segment Progression data:

  • DefaultPlayerData
    • For read-only player data and is game specific. Keys such as games_played, games_won, install_date and more are found here.
  • PlayerData
    • For player data and is game specific. Store and retrieve custom player statistics and other custom progression-related data here.
  • InGameItems
    • In-game items and is shared across all games in publisher's portfolio. Store and retrieve virtual goods and global custom progression-related data here.
info

In order to store data in the PlayerData and InGameItems namespaces, you must first create your custom keys via the Skillz Developer Console. Remember to publish your keys to Production when you are ready to distribute your game builds that contain Progression.

Get Progression User Data​

Retrieve data for the current user. The GetProgressionUserData method requires callback methods that allow you to handle success and fail scenarios.

public static void SkillzCrossPlatform.GetProgressionUserData(string progressionNamespace, List<string> userDataKeys, Action<Dictionary<string, ProgressionValue>> successCallback, Action<string> failureCallback)
Parameters​

progressionNamespace One of the namespace string constants

  • ProgressionNamespace.PLAYER_DATA
  • ProgressionNamespace.DEFAULT_PLAYER_DATA
  • ProgressionNamespace.IN_GAME_ITEMS

userDataKeys String key list of desired fields.

successCallback Action delegate to handle successful callback. The method must be defined in the implementation.

failureCallback Action delegate to handle failed callback. The method must be defined in the implementation.

Sample Implementation​

MatchController.cs
using SkillzSDK;
using UnityEngine;
using System;

public class MatchController : MonoBehaviour

    // Define list of keys to look up within the target namespace
    List<String> keys = new List<String>()
    {
        "games_played",
        "games_won",
        "average_score"
    };

    // Handle success response
    void OnReceivedData(Dictionary<string, SkillzSDK.ProgressionValue> data)
    {
        Debug.LogWarning("Success");
        // Do something with the data, such as populate a custom Progression scene

        // Example manipulation of the returned data
        // Printing each key/value to console
        foreach(var kvp in data)
            Debug.LogWarning("Progression default player data key: " + kvp.Key + ", value: " + kvp.Value.Value);
    }

    // Handle failure response
    void OnReceivedDataFail(string reason)
    {
        Debug.LogWarning("Fail: " + reason);
        // Continue without Progression data
    }

    public void GetData()
    {
        SkillzCrossPlatform.GetProgressionUserData(ProgressionNamespace.DEFAULT_PLAYER_DATA, keys, OnReceivedData, OnReceivedDataFail);
    }

Update Progression User Data​

Write data for the current user. The UpdateProgressionUserData method requires callback methods that allow you to handle success and fail scenarios.

info

The DefaultPlayerData namespace is read-only, and cannot be used with this method.

note

This method can update up to 25 elements per invocation.

public void SkillzCrossPlatform.UpdateProgressionUserData(string progressionNamespace, Dictionary<string, object> userDataUpdates, Action successCallback, Action<string> failureCallback)
Parameters​

progressionNamespace One of the namespace string constants

  • ProgressionNamespace.PLAYER_DATA
  • ProgressionNamespace.IN_GAME_ITEMS

userDataUpdates Dictionary of key/value pairs to be updated.

successCallback Action delegate to handle successful callback. The method must be defined in the implementation.

failureCallback Action delegate to handle failed callback. The method must be defined in the implementation.

Sample Implementation​

MatchController.cs
using Skillz;
using UnityEngine;

public class MatchController : MonoBehaviour

    // Define list of keys to update
    // Must match keys created in the Developer Console!
    Dictionary<String, object> updateDict = new Dictionary<String, object>()
    {
        { "achievement_level", 5.5 },
        { "combos_attained", 10 },
        { "character_color", "orange" }
    };
    // Handle success response
    void OnSentDataSuccess()
    {
        Debug.LogWarning("Successfully updated!");
    }

    // Handle failure response
    void OnSentDataFail(string reason)
    {
        Debug.LogWarning("Fail: " + reason);
    }

    void UpdateData()
    {
        SkillzCrossPlatform.UpdateProgressionUserData(ProgressionNamespace.PLAYER_DATA,
                                                        updateDict, OnSentDataSuccess, OnSentDataFail);
    }

Default Player Data​

These are automatically updating, read-only statistics from the Skillz platform

For use with GetProgressionUserData

info

Default Player Data values are calculated with completed matches that have a result. In progress games that have not yet matched with another player are excluded, and do not update the values.

KeyData TypeDescription
games_playedIntegerA count of the games a player has entered
cash_games_playedIntegerA count of the cash games a player has entered
games_wonIntegerA count of the total games a player has won
cash_games_wonIntegerA count of the total cash games a player has won
best_score_lifetimeFloatThe best score achieved by this player
average_scoreFloatThe average of all scores by this player
player_levelIntegerThe player’s level for this game
skillz_levelIntegerThe player’s global Skillz level
install_dateDateThe UTC date and timestamp the user installed the game

Progression Room Entry Point​

Configure Progression Room Entry Point​

  1. Configure your Entry Point within the Developer Console by clicking on Progression -> Entry Points. Be sure to complete all required fields. Hit Save to immediately see your room in Sandbox. Publish & Assign is used to share your entry point with your players in production.
    • You can create dynamic text in the Title and Subtitle fields by inserting your progression keys names directly into the input box. Example: You have ${Custom_Key_Name} challenges remaining!
  2. Implement OnProgressionRoomEnter from SkillzDelegate interface to load your progression scene
  3. Call ReturnToSkillz to return to the Skillz UI

Implement Progression Room​

For Unity, you need to implement the SkillzMatchDelegate interface as a regular C# class. This will be instantiated when launching Skillz later.

SkillzGameController.cs
using SkillzSDK;
using UnityEngine.SceneManagement;

public sealed class SkillzGameController : SkillzMatchDelegate
{
    private const string GameSceneName      = "Level1";  // Your game scene name
    private const string StartMenuSceneName = "StartMenu";  // Your menu scene (optional)
    private const string ProgressionSceneName = "PlayerProgress"; // Your progression scene

    public void OnMatchWillBegin(Match matchInfo)
    {
    }

    public void OnSkillzWillExit()
    {
    }

    public void OnProgressionRoomEnter()
    {
        // Load your progression scene here
        SceneManager.LoadScene(ProgressionSceneName);
    }
}

Progression Tools​

We've created some tools to help you with testing and troubleshooting your progression setup.

Player Data Lookup​

You can lookup a player by their username and view the current progression values stored for that player. This tool is available for both Sandbox and Production users.

The tool can be found in the Developer Console under Progression > Player Data by selecting the 3 dots on the right corner and clicking Player Lookup.

Progression Menu

Progression Player Lookup

Change Log​

You can see a log of all the changes that have been made to your custom progression keys and when they were done. The log can be found in the Developer Console under Progression > Player Data by selecting the 3 dots on the right corner and clicking Change Log

Progression Menu

Progression Change Log