The online save API provides user data storage for applications. It is useful for storing game states and other small data sets that a user may want to reuse later on a different device. There are API calls for submitting, retrieving, and removing data.

Submit

var data = { money: 10, weapon: 'bazooka' };
ID.api('user_data/submit', 'POST', {key: 'test', value: JSON.stringify(data)}, function(response){
    console.log(response);
});

Buffered Submit

If you want to save frequently, such as when a player changes a setting, the code must buffer and retry failed submits. Submitting data could fail, if things are saved too freqently.

var data = { money: 10, weapon: 'bazooka' };
var saveDelay;

function save() {
    var dataString = JSON.stringify(data);
    clearTimeout(saveDelay);

    saveDelay = setTimeout(function() {
        ID.api('user_data/submit', 'POST', {key: 'save', value: dataString}, function(response){
            console.log(response)
            if (response && response.status == 'not_saved') {
                console.log('Save failed, retrying in 5 secs');
                setTimeout(function() {
                    save();
                }, 5000);
            } else if (response && response.status == 'ok') {
                // save complete
            }
        });
    }, 3000);
}

Retrieve

ID.api('user_data/retrieve', 'POST', {key: 'test'}, function(response){
    try {
        console.log(res.jsondata);
        var data = JSON.parse(res.jsondata);
    } catch(e) {
        console.log(e);
    }
});

Remove

ID.api('user_data/remove', 'POST', {key: 'test'}, function(response){
    console.log(response);
});

Important Notes

  • Minimize the amount of data that should be saved. Consider ways to compress data.
  • It’s better to have 1 bigger save rather than 5 smaller ones. Try to condense calls into a single one.
  • Avoid auto-saving using a timer. If you have no other choice, do it no more than once a minute.
  • Try to not exceed 30Kb. There is some headroom, but larger saves may get rejected by the API.
  • Know that saving too frequently may not succeed.