Simperium Android

This is the official reference for the Simperium Android library. It's intended for developers who have already familiarized themselves with how Simperium works.

If you want to dive in deeper, have a look at the library source code on GitHub.

Simperium.newClient(String appId, String appKey, Context context)

This will create a new instance of Simperium. It is recommended to keep this as a private member of your Android application class. See the Simpletodo application class for an example.


appId — The unique appId from your Simperium App Dashboard.

appKey — The secret application key from your Simperium App Dashboard.

context — The Android application context.


Returns true if the current Simperium user needs to be authorized. Handy for checking if you need to show the built-in authorization activity for your app. For an example, see TodoListActivity.

No Parameters


Removes the authorized state for the user and signs them out from Simperium.

No Parameters

Save and sync changes to an object.

No Parameters

This will both save the object locally as well as attempt a sync with Simperium. See the ToDo class for an example on extending a BucketObject and syncing its properties with Simperium.

Simperium.bucket(String bucketName, BucketSchema<T> schema)

Gets the bucket for the specified bucket name and schema. The bucket can then be used to manage its objects.


bucketName — The name of the bucket.

schema — The bucket schema that was defined in your BucketObject class.


It's recommended to keep a private instance of the buckets you are using in your app in the Application class. See the TodoApplication and ToDo classes for examples.


Creates a new object using the schema defined in the BucketObject that relates to this Bucket.

No Parameters
Return Value

Returns a new Object of the BucketObject class for the bucket name.


See TodoListActivity for an example of creating a new bucket object.


Starts the bucket, which will start the websocket connection to Simperium and start listening for changes.

No Parameters

See TodoListActivity for an example of starting a bucket. It's recommended to start buckets in activities or fragments in the onResume() method.


Stops a bucket if it is running.

No Parameters

See TodoListActivity for an example of stopping a bucket. It's recommended to stop buckets in activities or fragments in the onPause() method.


Deletes all data from a bucket. Use with caution!

No Parameters


A listener that fires when a Simperium change has occurred for any object in the bucket. The listener callbacks are:

onSaveObject(Bucket bucket, Object<T>) : Called after an object is saved locally.

onDeleteObject(Bucket bucket, Object<T>) : Called after an object is deleted locally.

onBeforeUpdateObject(Bucket<T> bucket, Object<T>) : Called before a bucket object is about to be updated.

onNetworkChange(Bucket<T> bucket, Bucket.ChangeType changeType, String simperiumKey) : Called after a network change was received from Simperium.


See TodoListActivity for an example on using the bucket listeners.


Wrapper for a standard Android CursorAdapter that allows for access to the objects within a bucket.


Very handy for usage in CursorAdapters for ListFragments, Spinners, etc. See TodoListActivity for an example.


Queries a bucket for data and returns the result as a Bucket Cursor.


See the TodoAdapter in TodoListActivity for an example on querying for all objects within a bucket. For more complex queries, check out the where(), order() and include() methods in the Query class.