Examples

Obtain an API token: GetKey()

Getkey() function generates a new API token - if one does not exist. If a token exists, the method simply echoes back the existing token, so it is safe to call it multiple times. The function accepts the following parameters:

parameter name	type	description
key-id	string	Plain text string identifying this key (reserved for future use).
seed	array[string]	API token building blocks. Can be a combination of secret, user supplied, and public data.
callback	function	Callback function. Check result.status for 'success' or 'error'.

Include prefs.us in your project

<script src="https://prefs.us/prefs.us.js"></script>

Generate a an API token (a.k.a. API Key) , then retrieve it via a callback:

prefs_us.getkey('key-id', [ 'value1', 'value2', ... ],
    (response) => {
        console.log("API Key: " + response.token);
    }

Basic write operation

The segment below illustrates how to obtain an API token (using .getkey()) and then write a single value once a token is received. Notice, that in this example we don't provide a key for the data. That means that piece of data is very much mutable. Any subsequent calls to .write will override previously set value.

prefs_us.getkey('key-id', [ 'value1', 'value2', ... ],
    (response) => {
        prefs_us.write("Hello World!");
        prefs_us.write("Hey there World!");
});

prefs_us.read((R)=>{
    let greeting = R.values[0];
    //  greeting will now hold "Hey there World!"
});

Write a value identified by a key (a parameter).

prefs_us.key('theme').write('dark');
prefs_us.key('timeout').write('300');
prefs_us.key('game-stats').write('{ "score":"100", "level":"6" }');

The above can also be written out in a single stroke like this:

prefs_us.key('user-data').write('{ "theme":"dark", "timeout":"300", "score":"100", "level":"6" }');

Basic read operations

Saved data can be retrieved with a .read() function.

• if .key() is specified only data identified by the supplied key will be returned.
• if no .key() is specified, .read() call will return ALL data associated with a API token. Values will be returned in 'values' array in the response.

prefs_us.key('user-data').read( (result) => {
    console.log("Got data: %o", ressult.values);
});

Read ALL values associated with a key (notice that no key specified)

prefs_us.read( (result) => {
    console.log("all values: %o", ressult.values);
});

Hint

All key/value pairs can be grouped by project name, domain, and subdomain grouping directives.
See: Organizing data

Sample code: a typical use case

<script src="https://prefs.us/prefs.us.js"></script>

<input type="text" id="usr" />
<input type="password" id="pwd" />

<script>
/*
* Things we want stored about the user, can be JSON, a string, or an object.
*/
var user_data = '{ "level": "5", "score": "200" }';

/*
* A basic hashing function. Used to obscure your user's credentials.
* Generally we don't want to send those over the internets.
*/
const hashed = (string) => {
    let hash = 0;
    for (const char of string) {
        hash = (hash << 5) - hash + char.charCodeAt(0);
        hash |= 0; // Constrain to 32bit integer
    }
    return hash;
};

function mangled_parts() {
    return hashed(
        document.getElementById("usr").value
        + document.getElementById("pwd").value
    );
}

/*
* Called when someone clicks 'Save' button.
*/
function save_data() {
        prefs_us.getkey('myFirstKey', [ mangled_parts(), 'mysalt' ], (response) => {
        prefs_us.key("user-data").write(user_data);
    });
}

/*
* Called when someone clicks 'Read' button.
*/
function read_data() {
    prefs_us.getkey('myFirstKey', [ mangled_parts(), 'mysalt' ], (response) => {
        prefs_us.read( (result) => {
            user_data = result.values;
        });
    });
}
</script>

<button onclick="save_data()">Save user data</button>

<button onclick="read_data()">Get user data</button>

Collect emails from a product landing page

Store game data for a single user