Pages

January 28, 2010

Local Shared Object (Flash Cookie)

Posted by Jeremy Mitchell
From Wikipedia, a browser cookie is a "small piece of text stored on a user's computer by a web browser. A cookie consists of one or more name-value pairs containing bits of information".

A web application uses cookies for session management, personalization and tracking. Most browsers restrict the size of a cookie to 4 kb.

In a Flex application, storing data on a user's computer for later use is accomplished using Local Shared Objects rather than cookies. A Local Shared Object can store up to 100 kb of data without asking permission of the user. Unlike cookies that are capable of storing only text values, Local Shared Objects can store many data types including Number, String, Boolean, XML, Date, Array & Object. Instances of a custom class can also be stored in a Local Shared Object when the custom class is registered using the [RemoteClass] metadata tag.

Create / retrieve a Local Shared Object

The process for creating a new Local Shared Object or retrieving an existing Local Shared Object is identical. In both cases, the static method getLocal() is used.
public static function getLocal(name:String, localPath:String = null, secure:Boolean = false):SharedObject
First, perform a call to the static method getLocal() of the SharedObject class, and then save the reference in a variable.
var myNewLocalSharedObject:SharedObject = SharedObject.getLocal("myNewLocalSharedObject");
Flash Player will look in a local directory on the user's computer for a Local Shared Object named myNewLocalSharedObject. More specifically, it will look in a directory unique to the SWF's domain for a file named myNewLocalSharedObject.sol. If myNewLocalSharedObject.sol is found, a reference to the existing Local Shared Object is returned. Otherwise, myNewLocalSharedObject.sol is created and a reference is returned to the newly created Local Shared Object.

To determine whether a new or existing Local Shared Object was returned, query the size property.
var myNewLocalSharedObject:SharedObject = SharedObject.getLocal("myNewLocalSharedObject");

if (myNewLocalSharedObject.size > 0)
{
    trace("Existing Local Shared Object");
}
else
{
    trace("New Local Shared Object");
}
The getLocal() method has three parameters. They should be used as follows:
  • The name parameter is required to assign a name to the Local Shared Object.
  • The localPath parameter is optional and should be used if you anticipate multiple SWF files from the SAME domain needing access to one Local Shared Object, or if the SWF file responsible for creating the Local Shared Object may be moved to another location within the SAME domain.
  • The secure parameter is optional and is used to create a secure Local Shared Object. Once created, any subsequent calls to the secure Local Shared Object must be made by a SWF delivered over HTTPS.

Access / update a Local Shared Object

A Local Shared Object may have many attributes. For example, customer data may include name, age, address and order IDs. Each of these attributes is represented by a property of the Local Shared Object's data property. These values can be accessed, updated or deleted.
// retrieve a reference to the existing Local Shared Object (customerData.sol)
var so:SharedObject = SharedObject.getLocal("customerData");

// accessing the values of the Local Shared Object
var name:String = so.data.name;
var age:int = so.data.age;

// updating the values of the Local Shared Object
so.data.name= "John Smith";
so.data.age = 23;
so.data.orderIds = [23456, 24444, 25432];

// a custom class must be registered and marked serializable using the [RemoteClass] metadata tag
var address:Address = new Address();
address.street = "125 Foo Lane";
so.data.address = address;

// deleting values of the Local Shared Object
delete so.data.age;
delete so.data.orderIds;

Persist a Local Shared Object

Use the flush() method to immediately write a Local Shared Object to the user's computer.
public function flush(minDiskSpace:int = 0):String
A call to flush() returns one of two possible values, SharedObjectFlushStatus.PENDING or SharedObjectFlushStatus.FLUSHED. If more space is needed on the user's computer to persist the Local Shared Object, SharedObjectFlushStatus.PENDING is returned and a dialog box is presented to the user to obtain permission to allocate more space.



When the user selects "Allow" or "Deny" a NetStatusEvent.NET_STATUS event is dispatched targeting the Local Shared Object. Register an event listener to handle this event.
so.addEventListener(NetStatusEvent.NET_STATUS, netStatusHandler);
If the Local Shared Object is successfully written to the user's computer, SharedObjectFlushStatus.FLUSHED is returned and the user is not notified.

The flush() method has one parameter. It should be used as follows:
  • The minDiskSpace parameter is optional and is used to allocate additional space (over 100 kb) on the user's computer for the Local Shared Object. If used, a dialog box is presented to the user asking for permission to allocate additional space.
private function writeSharedObject():void
{
    var so:SharedObject = SharedObject.getLocal("mySO");
    so.data.name = "Jeremy Mitchell";
    try
    {
        // wrap in a try to handle a scenario where local storage has been disallowed
        so.flush(500000);
    }
    catch (e:Error)
    {
        trace("Local storage has been disabled for this domain");
    }
}
Note: The flush() method is not required to persist a Local Shared Object. When the application SWF closes, an attempt is made to persist all Local Shared Objects on the user's computer. However, if adequate space is not allocated for the Local Shared Object, the attempt will fail silently. Use the flush() method to ensure success and recover from any possible failure.

Delete a Local Shared Object

To purge the data of a Local Shared Object and delete it from the user's computer call the clear() method.
public function clear():void
For example:
var so:SharedObject = SharedObject.getLocal("loginInfo");
so.clear();

No comments: