Using AS3 SharedObject in Flash

By Blue_Chi | Flash CS3 | ActionScript 3.0 | Beginner

This tutorial will teach you how to use the AS3 SharedObject Class to store small amounts of data on the end user's machine. This stored data could be used to store a game's highscore, a user's login data, or any other information that you need to be remembered when the user visits your Flash movie again.

Shared Objects are very similar to cookies on a browser, however, they are not stored with the rest of your browsers cookies and are not deleted when the user deletes the regular cookies, instead they are completed managed by the Flash Player.

Following this tutorial requires you only to know the basics of AS3 variables.

The movie below shows an example in which the movie will remember the position of your objects even if you refresh the page.

This tutorial is divided into the following sections:

Using the getLocal() Method

The getLocal() method is the most fundamental aspect of the SharedObject Class. Unlike the majority of other ActionScript classes, you do use the new keyword to create your instance of this class, instead you use the getLocal() method. This methods checks if there is an existing instance of this object stored, and if not, it creates that object - otherwise it simply retrieves the existing object for you to manipulate.

This method is used in the following generalized code format:

var myVariableName:SharedObject = SharedObject.getLocal("mySharedObjectID");

The variable name is the reference you would use inside your program to refer to your Shared Object, while the Shared Object ID is the ID to be used only to store and retrieve that object from the Flash Player memory.

Even though you might want to store more than one piece of information, you can only use one Shared Object to store this data. The object can have as many data properties in it as long as the size of your Shared Object does not exceed the size limit set by the end user. This option is configured by the end user through his Flash Player settings. The default maximum size for Flash Player stored data is a 100KB - which is way more than what you would need for storing simple stuff like user data.

To start with our tutorial code, use the following to create your first Shared Object:

var mySharedObject:SharedObject = SharedObject.getLocal("republicofcode");

The following section will show you how to store data in this object.

Basic Usage of the SharedObjects Class

In order for your data to be stored inside a Shared Object the following must be done:

  1. Create an instance of the SharedObjects Class using the getLocal() method.
  2. Store data inside the SharedObjects instance.
  3. Write the ShareObjects instance into the player using the flush() method.

We have talked about the first step earlier, you simply create your Shared Object using the getLocal() method this way:

var mySharedObject:SharedObject = SharedObject.getLocal("republicofcode");

That should create our SharedObject for us. To add new data to this Shared Object we use the .data property to store whatever data we want in this object. For example, we are going to store the first and last name of the user, each in a separate data container:

var mySharedObject:SharedObject = SharedObject.getLocal("republicofcode");
mySharedObject.data.firstName = "John";
mySharedObject.data.lastName = "Doe";

This data is now attached to the Shared Object currently running in the movie, to store this data in the Flash Player and then to be able to retrieve it for future sessions we need to use the flush() method this way:

var mySharedObject:SharedObject = SharedObject.getLocal("republicofcode");
mySharedObject.data.firstName = "John";
mySharedObject.data.lastName = "Doe";
mySharedObject.flush();

This will store the data in the Flash Player.

Retrieving Data Stored in a SharedObject

Retrieving the data stored as in a Shared Object is very similar to the process for storing this data. This requires only two steps, the first is retrieving the actual Shared Object by using the getLocal() method and then retrieving the data through the data property.

We have earlier said that using the getLocal() method is a special process that attempts to check if your Shared Object exists before attempting to create one. If that object does exist, then it simply retrieves it and stores it in your variable:

var mySharedObject:SharedObject = SharedObject.getLocal("republicofcode");

Once you retrieve the SharedObject, you can dig up the content within it by directly accessing the information through the data property:

var mySharedObject:SharedObject = SharedObject.getLocal("republicofcode");
trace(mySharedObject.data.firstName);
trace(mySharedObject.data.lastName);

If you simply paste this code and test your movie your test window should output the names we specified earlier.

Deleting Data

If for some reason you want to delete all the data stored in your Shared Object, you can do that by using the clear() method:

var mySharedObject:SharedObject = SharedObject.getLocal("republicofcode");
mySharedObject.clear();

Practical Example

The code below shows you an example similar to the one shown at the top of the page where the position of a dragged object is stored for future sessions. In real life examples your code should first deal with the situation where no data is stored in your Shared Object as that would be the default position for most users.

In order to test this code you need to create a movie clip on stage and assign the instance name logo_mc to it:

var mySO:SharedObject = SharedObject.getLocal("republicofcode");

logo_mc.x = mySO.data.my_x;
logo_mc.y = mySO.data.my_y;

if (!mySO.data.my_y) {
logo_mc.x = 150;
logo_mc.y = 100;
}

logo_mc.addEventListener (MouseEvent.MOUSE_DOWN, onDown);
function onDown (e:MouseEvent):void {
var my_mc = e.target;
my_mc.startDrag ();
}

logo_mc.addEventListener (MouseEvent.MOUSE_UP, onUP);
function onUP (e:MouseEvent):void {
logo_mc.stopDrag ();
mySO.data.my_x = logo_mc.x;
mySO.data.my_y = logo_mc.y;
mySO.flush ();
}

logo_mc.buttonMode=true;

You can learn more about conditionals and event handing in AS3 by reviewing our tutorials on these topics.

This concludes our tutorial. I hope that you found it helpful. Feel free to post any questions you have at the Republic of Code Forum.

- End of Tutorial