Skip to main content

Choosing your App's Client-Side storage technology

This article will review the most popular client-side storage technologies. There are several ways for Overwolf apps to store data locally in the user's computer. Storing data persistently enables long-term access to the data, back ups of data or documents for offline use or for retrieval when necessary. It is also a way to retain user-specific settings for your app.

The following kinds of client-side storage are available:

  • Cookies.
  • Web storage.
    • Session storage.
    • Local storage.
  • IndexedDB.
  • Application cache.

Cookies​

Cookies are used to store various types of local information (e.g. a session id). Cookies are severely limited in size and can't store too much. They are sent back and forth with every HTTP and asset request (e.g for Images/CSS/JavaScript files).

Cookies are limited in their scope. Some of the limitations include:

  • Ability to store only up to 4KB of data.
  • Private to the app. An Overwolf app can only read the cookies it set itself, not other Overwolf apps cookies.
  • Limited total number (the exact number depends on the specific browser). If this number is exceeded, new cookies replace the older ones.

Cookies can be set or read server side, or client side. On the client side, cookies are exposed by the document object as document.cookie.

The example below is a simple JavaScript snippet to set a cookie that expires in one year:

// set a cookie that expires in 1 year counted in seconds
document.cookie = 'name=OW; max-age=31536000' 

// return a string with all the cookies set for the page, semicolon separated
const cookies = document.cookie

Web Storage​

Web Storage provides a way to store key:value pairs in a user's browser.

  • Web Storage is persistent. Once a value is stored, it doesn't disappear or expire until the application or the user explicitly removes it.
  • Web Storage can handle large amounts of data. Current browsers limit total size per storage area to 5Mb.
  • Web Storage doesn't depend on the server and sends no data to the server. Use this online or offline. Store data locally and sync it with the server asynchronously.
  • Web Storage provides four primary methods: getItem(key);, setItem(key,value);, removeItem(key);, and clear().

Web Storage includes two different types of storage: SessionStorage and LocalStorage.

Session storage​

SessionStorage limits the scope of data saved in the current browser window to just that browser window. For example, when used with an ecommerce application sessionStorage records the contents of a user's shopping cart eliminating the potential for accidental double purchases.

LocalStorage​

LocalStorage persists across windows and tabs within a single browser. So, if you have the same site open in three windows in Chrome, all the tabs could share the same localStorage container.

LocalStorage databases impose a size limit of ~50Mb (Since Overwolf v0.161. Before, the size was 5Mb).

Use the Web Storage API to set and get data

For example:

localStorage.setItem( "firstname", "Wolf" );
var name = localStorage.getItem( "firstname" );

Web Storage can be used anywhere you would normally have used cookies. It provides what's perhaps the simplest way to set and retrieve key-value pairs in a browser.

IndexedDB​

IndexedDB (Indexed Database) is an API for storing and retrieving data using an indexed, transactional database of key:value pairs on the user's computer. IndexedDB provides faster, more sophisticated data storage and retrieval than simple key:value pair storage available from Web Storage or cookies. All major browsers except Safari currently support IndexedDB.

IndexedDB offers the following benefits over Web Storage:

  • Indexed data can be searched efficiently.
  • Databases allow multiple values to be stored as a key, whereas key:value data requires each key to be unique.
  • Transactional databases offer some protection against system and application failures. If a transaction doesn't successfully complete, it can be rolled back.
  • IndexedDB databases impose no size limitations.

Use the IndexedDB API to set and get data.

For example:

var db; // create empty variable to hold database if opening succeeds
var request = indexedDB.open("myDatabase"); //the first step is to open a database

request.onsuccess = (event) => {
  db = request.result; // if things go well, we will get the db in the `result` property of our request
}

//create an object store (which is something very much like a table)
var objectStore = db.createObjectStore("players", {keyPath: "id"}); 

objectStore.add(customerData[i]); //add data

IndexedDB is recommended if you're building an application that needs to store structured data. However, there may be a steep learning curve. Use the TODO-notifications sample app to get you started.

Application Cache​

Application cache isn't like the other client side storage methods. It is important for enabling offline client side web apps. Application cache uses a simple text document that lists the resources that should and shouldn't be cached. This indicates to the browser to download certain files, hold onto them and use the cached version rather than make a request to the server. Every major Web browser supports the Application Cache.

For more information about app cache, see A beginner's guide to using the application cache.