A shared object, sometimes referred to as a "Flash cookie," is a data file that can be created on your computer by the sites that you visit. Shared objects are most often used to enhance your web-browsing experience--for example, by allowing you to personalize the look and feel of a website that you frequently visit. Shared objects, by themselves, can't do anything to or with the data on your computer. More important, shared objects can never access or remember your e-mail address or other personal information--unless you willingly provide such information.

New shared object instances can be created using the static SharedObject.getLocal() or SharedObject.getRemote() methods. The getLocal() method attempts to load a locally persistent shared object that is available only to the current client, whereas the getRemote() method attempts to load a remote shared object that can be shared across multiple clients by means of a server, such as Flash Media Server. If the local or remote shared object does not exist, the getLocal() and getRemote() methods will create a new SharedObject instance.

The following code attempts to load a local shared object named test. If this shared object doesn't exist, a new shared object with this name will be created.

var so:SharedObject = SharedObject.getLocal("test");
trace("SharedObject is " + so.size + " bytes");

If a shared object named test cannot be found, a new one is created with a size of 0 bytes. If the shared object previously existed, its current size (in bytes) is returned.

You can store data in a shared object by assigning values to the data object, as seen in the following example:

var so:SharedObject = SharedObject.getLocal("test");
so.data.now = new Date().time;
trace(so.data.now);
trace("SharedObject is " + so.size + " bytes");

If there is already a shared object with the name test and the parameter now, the existing value is overwritten. You can use the SharedObject.size property to determine if a shared object already exists, as the following example shows:

var so:SharedObject = SharedObject.getLocal("test");
if (so.size == 0)
{
    // Shared object doesn't exist.
    trace("created...");
    so.data.now = new Date().time;
}
trace(so.data.now);
trace("SharedObject is " + so.size + " bytes");

The previous code uses the size parameter to determine if the shared object instance with the specified name already exists. If you test the following code, you'll notice that each time you run the code, the shared object is recreated. In order for a shared object to be saved to the user's hard drive, you must explicitly call the SharedObject.flush() method, as the following example shows:

var so:SharedObject = SharedObject.getLocal("test");
if (so.size == 0)
{
    // Shared object doesn't exist.
    trace("created...");
    so.data.now = new Date().time;
}
trace(so.data.now);
trace("SharedObject is " + so.size + " bytes");
so.flush();

When using the flush() method to write shared objects to a user's hard drive, you should be careful to check whether the user has explicitly disabled local storage using the Flash Player Settings Manager (www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager07.html), as shown in the following example:

var so:SharedObject = SharedObject.getLocal("test");
trace("Current SharedObject size is " + so.size + " bytes.");
so.flush();

Values can be retrieved from a shared object by specifying the property's name in the shared object's data property. For example, if you run the following code, Flash Player will display how many minutes ago the SharedObject instance was created:

var so:SharedObject = SharedObject.getLocal("test");
if (so.size == 0)
{
    // Shared object doesn't exist.
    trace("created...");
    so.data.now = new Date().time;
}
var ageMS:Number = new Date().time - so.data.now;
trace("SharedObject was created " + Number(ageMS / 1000 / 60).toPrecision(2) + " minutes ago");
trace("SharedObject is " + so.size + " bytes");
so.flush();

The first time the previous code is run, a new SharedObject instance named test will be created and have an initial size of 0 bytes. Because the initial size is 0 bytes, the if statement evaluates to true and a new property named now is added to the local shared object. The shared object's age is calculated by subtracting the value of the now property from the current time. Each subsequent time the previous code is run, the size of the shared object should be greater than 0, and the code will trace how many minutes ago the shared object was created.

Subtopics

• Displaying contents of a shared object
• Creating a secure SharedObject

Displaying contents of a shared object

Values are stored in shared objects within the data property. You can loop over each value within a shared object instance by using a for..in loop, as the following example shows:

var so:SharedObject = SharedObject.getLocal("test");
so.data.hello = "world";
so.data.foo = "bar";
so.data.timezone = new Date().timezoneOffset;
for (var i:String in so.data)
{
    trace(i + ":\t" + so.data[i]);
}

Creating a secure SharedObject

When you create either a local or remote SharedObject using getLocal() or getRemote(), there is an optional parameter named secure that determines whether access to this shared object is restricted to SWF files that are delivered over an HTTPS connection. If this parameter is set to true and your SWF file is delivered over HTTPS, Flash Player creates a new secure shared object or gets a reference to an existing secure shared object. This secure shared object can be read from or written to only by SWF files delivered over HTTPS that call SharedObject.getLocal() with the secure parameter set to true. If this parameter is set to false and your SWF file is delivered over HTTPS, Flash Player creates a new shared object or gets a reference to an existing shared object.

This shared object can be read from or written to by SWF files delivered over non-HTTPS connections. If your SWF file is delivered over a non-HTTPS connection and you try to set this parameter to true, the creation of a new shared object (or the access of a previously created secure shared object) fails, an error is thrown, and the shared object is set to null. If you attempt to run the following snippet from a non-HTTPS connection, the SharedObject.getLocal() method will throw an error:

try
{
    var so:SharedObject = SharedObject.getLocal("contactManager", null, true);
}
catch (error:Error)
{
    trace("Unable to create SharedObject.");
}

Regardless of the value of this parameter, the created shared objects count toward the total amount of disk space allowed for a domain.